Deploy Button
Deploy public Git projects with the Deploy Button, providing an easy-to-use 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.
Generate Your Own
Customize the above Deploy Button snippets starting with a public Git repository URL from GitHub, GitLab, or Bitbucket.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.