Vercel for GitHub automatically deploys your GitHub projects with Vercel, providing Preview Deployment URLs, and automatic Custom Domain updates.
Vercel for GitHub deploying a pull request automatically.
Deploying a GitHub Repository
Learn how to create a new Vercel Project from a GitHub repository and enable automatic deployments on every branch push here.
Changing the GitHub Repository of a Project
If you'd like to connect your Vercel Project to a different GitHub repository or disconnect it, you can do so from the Git section in the Project Settings.
Default Behaviour
A Deployment for Each Push
Vercel for GitHub will deploy every push by default. This includes pushes and pull requests made to branches. This allows those working within the repository to preview changes made before they are pushed to production.
With each new push, if Vercel is already building a previous commit, the current build will be canceled to build the most recent commit so that you always have the latest changes deployed as quickly as possible.
Updating the Production Domain
If Custom Domains are set from a project domains dashboard, pushes and merges to the Production Branch (commonly "main") will be made live to those domains with the latest deployment made with a push.
If you decide to revert a commit that has already been deployed to production, the previous Production Deployment from a commit will automatically be made available at the Custom Domain instantly; providing you with instant rollbacks.
Preview URLs for the Latest Changes for Each Pull Request
The latest push to any pull request will automatically be made available at a unique preview URL based on the project name, branch, and team or username. These URLs will be provided through a comment on each pull request.
Deployment Authorizations for Forks
If you receive a pull request from a fork of your repository and there is either a change to the vercel.json file or there are Environment Variables used in your project; Vercel will require an authorization from you or a member of your team to deploy the pull request.
This behavior protects you and your project from a leak of sensitive information.
Extending Your GitHub Workflow
Vercel for GitHub uses the deployment API to bring you an extended user interface both in GitHub, when showing deployments, and Slack, if you have notifications setup using the Slack GitHub app.
You will see all of your deployments, production or preview, from within GitHub on its own page. See this page for example: https://github.com/vercel/vercel/deployments
Due to using GitHub's Deployments API, you will also be able to integrate with other services through GitHub's checks. Vercel will provide the deployment URL to the checks that require it, for example; to a testing suite such as Checkly.
Configuring Vercel for GitHub
To configure the Vercel for GitHub integration, see the configuration reference for Git.
System Environment Variables
You may want to use different workflows and APIs based on Git information. To support this, the following System Environment Variables are exposed to your Deployments:
Name | Description |
|---|---|
VERCEL_GIT_PROVIDER | The Git Provider the deployment is triggered from. In the case of GitHub, the value is always github. |
VERCEL_GIT_REPO_SLUG | The origin repository of the app on GitHub. Example: my-site. |
VERCEL_GIT_REPO_OWNER | The GitHub organization that owns the repository the deployment is triggered from. Example: acme. |
VERCEL_GIT_REPO_ID | The ID of the GitHub repository the deployment is triggered from. Example: 117716146. |
VERCEL_GIT_COMMIT_REF | The GitHub branch that the deployment was made from. Example: improve-about-page. |
VERCEL_GIT_COMMIT_SHA | The GitHub SHA of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081. |
VERCEL_GIT_COMMIT_MESSAGE | The message attached to the GitHub commit the deployment was triggered by. Example: Update about page. |
VERCEL_GIT_COMMIT_AUTHOR_LOGIN | The GitHub username belonging to the author of the commit that the project was deployed by. Example: johndoe. |
VERCEL_GIT_COMMIT_AUTHOR_NAME | The GitHub name belonging to the author of the commit that the project was deployed by. Example: John Doe. |
Required Permissions
We require some permissions through our Vercel for GitHub integration. Below are listed the permissions required and a description for what they are used for.
Repository Permissions
Repository permissions allow us to interact with repositories belonging to or associated with (if permitted) the connected account.
Permission | Read | Write | Description |
|---|---|---|---|
Administration | Y | Y | Allows us to create repositories on the user's behalf. |
Checks | Y | Y | Allows us to add checks against source code on push. |
Contents | Y | Y | Allows us to fetch and write source code for new project templates for the connected user or organization. |
Deployments | Y | Y | Allows us to synchronize deployment status between GitHub and the Vercel infrastructure. |
Pull Requests | Y | Y | Allows us create deployments for each Pull Request (PR) and comment on those PR's with status updates. |
Issues | Y | Y | Allows us to interact with Pull Requests as with the Pull Requests permissions due to GitHub requiring both for access. |
Metadata | Y | N | Allows us to read basic repository metadata to provide a detailed dashboard. |
Web Hooks | Y | Y | Allows us to react to various GitHub events. |
Commit Statuses | Y | Y | Allows us to synchronize commit status between GitHub and Vercel. |
Organization Permissions
Organization permissions allow us to offer an enhanced experience through information about the connected organization.
Permission | Read | Write | Description |
|---|---|---|---|
Members | Y | N | Allows us to offer a better team onboarding experience. |
User Permissions
User permissions allow us to offer an enhanced experience through information about the connected user.
Permission | Read | Write | Description |
|---|---|---|---|
Email addresses | Y | N | Allows us to associate an email with a GitHub account. |
Sign up with another GitHub Account
To sign up on Vercel with a different GitHub account, sign out of your current GitHub account:
Sign out of GitHub.
Then, restart the Vercel signup process.