Deploy Button

Deploy public Git projects with the Deploy Button, providing an intuitive flow to set up new projects with Vercel and GitHub, GitLab, or Bitbucket.

An example Deploy Button using the following HTML snippet.

Snippets

Use the snippets below in your Git repositories or your dashboards for users to deploy.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world)

A Markdown snippet that shows a linked Deploy Button.

Generate Your Own

Customize the above Deploy Button snippets starting with a public Git repository URL from GitHub, GitLab, or Bitbucket.

Git Repository

Learn more about the Git Repository URL parameter →

You can customize the Project Creation Flow and created project with the following additional settings. For more information see the URL Parameter Reference.

Environment Variables

Define Environment Variable Keys that the Git repository needs to deploy successfully. The values will be filled in by the user.

Environment Variables Keys

Learn more about the Environment Variable parameters →

Add a description with additional information and a link to documentation that helps users understand what they are providing values for.

Environment Variables Description

Environment Variables Link

Defaults

If you're setting up a project on behalf of the user and already know what name the user likely wants, enter a default project name. Additionally, fill this in for the repository name.

Set a default repository name for the new Git repository created by the user in the Project Creation Flow.

Default Project Name

Default Git Repository Name

Redirect

The Redirect URL parameter allows you to redirect the user back to your platform on the event of a successful deployment and receive information on the created project.

Redirect URL

Learn more about the Redirect URL parameter →

Set a Developer ID to show a logo and name from an Integration by using its Client ID, found in the Integration Developer Console.

Developer ID

Learn more about the Developer ID parameter →

Set a name for a Deploy Hook to receive a Deploy Hook URL in return when redirecting the user from the Project Creation Flow.

Deploy Hook Name

Learn more about the Deploy Hook parameter →

Demo

To showcase a successful deployment to the user clicking a Deploy Button, you can customize the Project Creation Flow's landing page with a Demo Card.The Demo Card contains a title, a description, an image, and a link. All of them are required for the Demo Card to show on the page.

Demo Title

Learn more about the Demo Title parameter →

Demo Description

Learn more about the Demo Description parameter →

Demo URL

Learn more about the Demo URL parameter →

Demo Image

Learn more about the Demo Image parameter →

Integrations

Integrations let you connect your Vercel Project with third-party services to automate aspects of your workflow.When Integrations IDs are specified, the corresponding Integrations are required to be installed for the Vercel Project. If needed, they can also be marked as optional using the Optional Integrations parameter.Integration IDs can be found in the Integrations Console.

Integration IDs

Learn more about Integrations →

Additionally, you can specify an external ID or reference that will be passed to the Redirect URL of each of the required Integrations.

External ID

Learn more about the External ID parameter →

Allow for skipping Integrations or adding only one of them

Learn more about the Optional Integrations parameter →

What's a Deploy Button?

The Deploy Button allows users to deploy a new project through the Vercel Project Creation Flow, while cloning the source Git repository to GitHub, GitLab, or Bitbucket.

You can create your Deploy Button with the generator above.

The Vercel Project Creation Flow allows users to deploy a Git repository, create a project with Vercel, and clone the source repository into their GitHub, GitLab, or Bitbucket account.

The Vercel Project Creation Flow deploying a Next.js Commerce project.

With the Vercel Project Creation Flow, you can add various URL query parameters to control the experience a user will have, depending on the requirements of your project.

What follows below is a reference of what each parameter achieves within a Deploy Button URL. Use the Deploy Button Generator to create your own Deploy Button.

Source

Repository URL

Parameter: repository-url
Value: The source Git repository URL.
Type: String

The Repository URL parameter allows you to define a Git repository URL, optionally including the subdirectory within a repository, that users will clone into their GitHub, GitLab, or Bitbucket account when going through the Vercel Project Creation Flow.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world

An example Deploy Button source URL using the repository-url parameter.

Note: The Repository URL parameter is required when sending a user to the Vercel Project Creation Flow to set up a project from a GitHub, GitLab, or Bitbucket repository.

Project Name

Parameter: project-name
Value: A default project name.
Type: String

The Project Name parameter allows you to define a default project name.

This parameter is useful for cases where already know what the user would like to name their project. For example, if you are sending the user to the Project Creation Flow from an application that has already set up a project for the user that will connect to the created Vercel project.

Note: If there is an existing project using the name passed with this parameter, the user will be required to define a new project name, and therefore the project is not guaranteed to have the specified name.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&project-name=my-awesome-project

An example Deploy Button source URL using the project-name parameter.

Repository Name

Parameter: repository-name
Value: A default repository name (no spaces).
Type: String

The Repository Name parameter allows you to define a default repository name.

Similar to the Project Name parameter, this parameter is useful in cases where you already know what the user wants to name their repository.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&repository-name=my-awesome-project

An example Deploy Button source URL using the repository-name parameter.

Demo

Demo Title

Parameter: demo-title
Value: The title of an example deployment.
Type: String

This parameter allows you to specify the title of an example of a successful deployment.

The parameter is part of the Demo Card parameters. The Demo Card should showcase an example of a successful deployment to the user clicking the Deploy Button and entering the Project Creation Flow.

Note: The Demo card is displayed only when all demo-* parameters are provided.

The Demo Title parameter is displayed on the Demo Card.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&demo-title=APM%20Story

An example Deploy Button source URL using the demo-title parameter.

Demo Description

Parameter: demo-description
Value: The description of the example deployment.
Type: String

This parameter allows you to specify the description of an example of a successful deployment.

The parameter is part of the Demo Card parameters. The Demo Card should showcase an example of a successful deployment to the user clicking the Deploy Button and entering the Project Creation Flow.

Note: The Demo card is displayed only when all demo-* parameters are provided.

The Demo Description is displayed on the Demo Card.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&demo-description=A%20statically%20generated%20blog%20example%20using%20Next.js%20%and%20DatoCMS

An example Deploy Button source URL using the demo-description parameter.

Demo URL

Parameter: demo-url
Value: The URL of the example deployment.
Type: String

This parameter allows you to specify the URL of an example of a successful deployment.

The parameter is part of the Demo Card parameters. The Demo Card should showcase an example of a successful deployment to the user clicking the Deploy Button and entering the Project Creation Flow.

Note: The Demo card is displayed only when all demo-* parameters are provided.

Clicking on the Demo Card will link the user to the URL specified by Demo URL.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&demo-url=https%3A%2F%2Fnextjs.org

An example Deploy Button source URL using the demo-url parameter.

Demo Image

Parameter: demo-image
Value: The URL of the screenshot of an example deployment.
Type: String

This parameter allows you to specify the URL of the screenshot of an example of a successful deployment.

The parameter is part of the Demo Card parameters. The Demo Card should showcase an example of a successful deployment to the user clicking the Deploy Button and entering the Project Creation Flow.

Note: The Demo card is displayed only when all demo-* parameters are provided.

The image specified by Demo Image is displayed on the Demo Card.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&demo-image=https%3A%2F%2Fexample.com%2Fimage.png

An example Deploy Button source URL using the demo-image parameter.

Build Settings

Build Command

Parameter: build-command
Value: The value of the Build Command defined in the Build & Development section of the General Project Settings. Setting this value is equivalent to enabling the Override toggle for that field in the dashboard.
Type: String

This allows you to define a custom Build command that is normally automatically configured based on your Project's framework.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&build-command=npm%20run%20build

A source URL using the build-command parameter to set the Build command tonpm run build

Install Command

Parameter: install-command
Value: The value of the Install Command defined in the Build & Development section of the General Project Settings. Setting this value is equivalent to enabling the Override toggle for that field in the dashboard.
Type: String

This allows you to define a custom Install command that is normally automatically configured based on the following:

If pnpm-lock.yaml is present, the Install Command is pnpm install
- If "lockfileVersion": 5.4 is present in the lock file, pnpm 7 is used
- Otherwise, pnpm 6 is used
If package-lock.json is present, the Install Command is npm install
- If "lockfileVersion": 2 is present in the lock file, npm 8 is used
- Otherwise npm 6 is used
Otherwise, the Install Command is yarn install

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&install-command=npm%20install

A source URL using the install-command parameter to set the Install command tonpm install

Development Command

Parameter: dev-command
Value: The value of the Development Command defined in the Build & Development section of the General Project Settings. Setting this value is equivalent to enabling the Override toggle for that field in the dashboard.
Type: String

This allows you to define a custom development command if you are using vercel dev to test your project locally. Each framework has its own development command and this will be set automatically based on your selected framework.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&dev-command=next%20dev%20--port%20%24PORT

A source URL using the dev-command parameter to set the Development command tonext dev --port $PORT

Ignored Build Command

Parameter: ignore-command
Value: The value of the Ignored Build Step defined in the Git section of the General Project Settings.
Type: String

This allows you to define an Ignored Build Step to determine when your project should build and deploy.

https://vercel.com/new/clone?repository-url=https://github.com/vercel/examples/tree/main/solutions/monorepo&project-name=monorepo&repo-name=monorepo&root-directory=app&build-command=cd%20..%20%26%26%20npm%20run%20build&install-command=cd%20..%20%26%26%20npm%20i&ignore-command=npx%20turbo-ignore

A source URL using the ignore-command parameter to set the Ignored Build Step command tonpx turbo-ignore

Root Directory

Parameter: root-directory
Value: The value of the Root Directory defined in the General section of the Project Settings.
Type: String

This allows you to define the path of the directory relative to the root of the Project folder where your source code is located. By default it is empty and equivalent to the root of the repository.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-support%2Fyarn-ws-monorepo&root-directory=apps%2Ffrontend

A source URL using the root-directory parameter for a monorepo where one of the applications is located in the folder apps/frontend

Output Directory

Parameter: output-directory
Value: The value of the Output Directory defined in the General section of the Project Settings.
Type: String

This allows you to define the output directory's path relative to the Project folder's root. Usually, this is automatically configured based on your Project's framework.

https://vercel.com/new/git/external?repository-url=https://github.com/vercel/examples/tree/main/solutions/nx-monorepo&project-name=nx-monorepo&repository-name=nx-monorepo&build-command=npx%20nx%20build%20app%20--prod&ignore-command=npx%20nx-ignore%20app&output-directory=dist%2Fapps%2Fapp%2F.next

A source URL using the output-directory parameter for a monorepo where application output is generated to dist/.

Environment Variables

Required Environment Variables

Parameter: env
Value: A comma-separated list of required Environment Variable keys e.g., TEST_KEY,TEST_API_KEY.
Type: String []

The Required Environment Variables parameter allows you to require users to fill in values of Environment Variables the new project needs to run successfully.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&env=PUBLIC_API_KEY,API_SECRET_KEY

An example Deploy Button source URL using the env parameter.

Note: You cannot pass Environment Variable values using this parameter due to the URL being saved in the browser history, and thus not being a secure method.

Environment Variables Description

Parameter: envDescription
Value: A short description of the Required Environment Variables.
Type: String

The Environment Variables Description parameter allows you to define a URL encoded string that describes to a user what the Required Environment Variables are used for.

Note: The description provided through this parameter will only show if Required Environment Variables are set.

An example Configure Project step using the Environment Variable Description parameter to add context.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&env=PUBLIC_API_KEY,API_SECRET_KEY&envDescription=Enter%20your%20public%20API%20Key.

An example Deploy Button source URL using the envDescription parameter.

Environment Variables Link

Parameter: envLink
Value: A link to an explanation of the Required Environment Variables.
Type: String

The Environment Variable Link parameter allows you to attach a link to external documentation that helps the user find more information about where the values for the Environment Variables can be found and what they are for.

Note: The description provided through this parameter will only show if Required Environment Variables are set.

An example Configure Project step using the Environment Variable Link parameter to add context.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&env=PUBLIC_API_KEY,API_SECRET_KEY&envDescription=Enter%20your%20public%20API%20Key.&envLink=https%3A%2F%2Fvercel.com%2Fdocs

An example Deploy Button source URL using the envLink parameter.

Note: The snippet above is just an example of using a URL with the envLink parameter. Please provide users with a specific link instead of top-level documentation.

Integrations

Required Integrations

Parameter: integration-ids

Value: A comma-separated list of required Integrations IDs e.g. oac_4mkAfc68cuDV4suZRlgkn3R9, oac_JI9dt8xHo7UXmVV6mZTygMNZ

Type: String[]

This parameter allows you to specify a list of Integration IDs. When specified, the corresponding Integrations will be required to be added before the Project can be imported.

You can find the IDs of your Integrations in the Integrations Console.

Note: You can add up to 3 Integrations per Project.

Note: Integrations which contain a "UI Hook URL" cannot be rendered in the Deploy Flow.

The page in the Project Creation Flow to add the Integrations.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&integration-ids=oac_1mkAfc68cuDV4suZRlgkn3Re

An example Deploy Button source URL using the integration-ids parameter.

Skippable Integrations

Parameter: skippable-integrations
Value: Mark the list of provided Integrations as optional
Type: Number

If this parameter is present, the user will be able to add one of the provided Integrations or skip them entirely, instead of being forced to add all of them.

Because the user will only be able to select one (not multiple) of the optional Integrations, they should all serve the same purpose. For example, if the purpose is error tracking, the Integrations Sentry and Datadog could be defined here.

Note: To use this parameter, you also need to specify at least one Integration.

The "Skip" button allows you to entirely skip adding the Integrations.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&integration-ids=oac_1mkAfc68cuDV4suZRlgkn3Re&skippable-integrations=1

An example Deploy Button source URL using the integration-ids and skippable-integrations parameters.

Callback

Redirect URL

Parameter: redirect-url
Value: The URL to redirect the user to in the event of a successful deployment.
Type: String

The Redirect URL parameter allows you to define a URL, other than the newly created Vercel project, to send the user to after a successful deployment.

This parameter is helpful if you are sending a user from an application, to deploy a project with Vercel, but want the user to continue with your application with a project created and deployed.

An example of the redirect UI when a Redirect URL parameter is used.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&redirect-url=my-headless-application.com

An example Deploy Button source URL using the redirect-url parameter.

Note: Provide a custom name and logo for the redirect UI by using the Developer ID parameter.

Callback Parameters

Vercel additionally attaches some "Callback Parameters" to the defined Redirect URL when the user is redirected. The following parameters give you access to information about the project the user has created and deployed, for you to integrate with Vercel after the user is sent back to you.

Parameter	Description
`project-dashboard-url`	The URL to view the Project that was created through the Project Creation Flow on the Vercel Dashboard.
`project-name`	The Name of the Project that was created through the Project Creation Flow.
`deployment-dashboard-url`	The URL to view the Deployment that was created through the Project Creation Flow on the Vercel Dashboard.
`deployment-url`	The URL of the deployment that was created through the Project Creation Flow. This contains the default production domain that was automatically generated for the project that was created.
`repository-url`	The URL of the Git repository that was created through the Project Creation Flow, within the user's selected Git account (GitHub, GitLab, or Bitbucket).
`production-deploy-hook-url` (conditional)	The URL of a Deploy Hook. Requires the `production-deploy-hook` parameter.

Developer ID

Parameter: developer-id
Value: Integration Client ID.
Type: String

The Developer ID parameter allows you to define a Vercel Integration Client ID which will then attach your logo and name to the UI when using the Redirect URL parameter.

You can find the Developer ID listed as "Client ID" in your Integrations Developer Console.

An example of the redirect UI with a Developer logo and name when the Redirect URL and Developer ID parameters are used.

Note: This parameter requires the Redirect URL parameter to be set and also that the Integration website field matches the Redirect URL value.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&redirect-url=https%3A%2F%2Fmy-headless-application.com&developer-id=oac_7rUTiCMow23Gyfao9RQQ3Es2

An example Deploy Button source URL using the redirect-url and the developer-id parameters.

External ID

Parameter: external-id
Value: An external ID or reference of your choice
Type: String

This parameter allows you to pass the ID or reference of your choice to the Project Creation Flow.

The query parameter will be relayed to the Redirect URL of each required Integration when the user adds them in the Project Creation Flow.

Note: To use this parameter, you also need to specify at least one Integration.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&integration-ids=oac_1mkAfc68cuDV4suZRlgkn3Re&external-id=1284210

An example Deploy Button source URL using the integration-ids and external-id parameters.

Deploy Hook

Parameter: production-deploy-hook
Value: Name of the Deploy Hook to set up.
Type: String

The Deploy Hook parameter allows you to receive a URL when also using the Redirect URL parameter, which you can use to redeploy user's projects for them.

This is useful if you are directing a user to deploy a project that works with your application, for example a headless CMS, and you need to redeploy the user's project in case of a content change that needs to be rebuilt.

The value of this parameter should be the name of the Deploy Hook you want to create for the user.

When redirected back to your application upon a successful deployment for the user, you will get the production-deploy-hook-url callback parameter in addition to the default callback parameters.

Note: This parameter requires the Redirect URL parameter to also be set.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&redirect-url=https%3A%2F%2Fmy-headless-application.com&production-deploy-hook=MyHeadlessProject

An example Deploy Button source URL using the redirect-url and the production-deploy-hook parameters.

Was this helpful?