Deploying GitHub Projects with Vercel

Vercel for GitHub automatically deploys your GitHub projects with Vercel, providing Preview Deployment URLs, and automatic Custom Domain updates.
Table of Contents

Vercel for GitHub automatically deploys your GitHub projects with Vercel, providing Preview Deployment URLs, and automatic Custom Domain updates.

The Deploying a Git repository guide outlines how to create a new Vercel Project from a GitHub repository, and enable automatic deployments on every branch push.

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.

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 on the same branch, the current build will complete and any commit pushed during this time will be queued. Once the first build completes, the most recent commit will begin deployment and the other queued builds will be cancelled. This ensures that you always have the latest changes deployed as quickly as possible.

You can disable this feature for GitHub by configuring the github.autoJobCancellation option in your vercel.json file.

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.

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. Vercel also supports Comments on preview deployments made from PRs on GitHub. Learn more about Comments on preview deployments in GitHub here.

If you receive a pull request from a fork of your repository that includes a change to the vercel.json file or the Project has Environment Variables, Vercel will require authorization from you or a Team Member to deploy the pull request.

This behavior protects you from leaking sensitive Project information.

You can disable Git Fork Protection in the Security section of your Project Settings.

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.

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.

To configure the Vercel for GitHub integration, see the configuration reference for Git.

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:


The Git Provider the deployment is triggered from. In the case of GitHub, the value is always github.

The origin repository of the app on GitHub.

.env
VERCEL_GIT_REPO_SLUG=my-site

The GitHub organization that owns the repository the deployment is triggered from.

.env
VERCEL_GIT_REPO_OWNER=acme

The ID of the GitHub repository the deployment is triggered from.

.env
VERCEL_GIT_REPO_ID=117716146

The GitHub branch that the deployment was made from.

.env
VERCEL_GIT_COMMIT_REF=improve-about-page

The GitHub SHA of the commit the deployment was triggered by.

.env
VERCEL_GIT_COMMIT_SHA=fa1eade47b73733d6312d5abfad33ce9e4068081

The message attached to the GitHub commit the deployment was triggered by.

.env
VERCEL_GIT_COMMIT_MESSAGE=Update about page

The GitHub username belonging to the author of the commit that the project was deployed by.

.env
VERCEL_GIT_COMMIT_AUTHOR_LOGIN=johndoe

The GitHub name belonging to the author of the commit that the project was deployed by.

.env
VERCEL_GIT_COMMIT_AUTHOR_NAME=John Doe

The GitHub pull request id the deployment was triggered by. If a deployment is created on a branch before a pull request is made, this value will be an empty string.

.env
VERCEL_GIT_PULL_REQUEST_ID=23

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 allow us to interact with repositories belonging to or associated with (if permitted) the connected account.

PermissionReadWriteDescription
AdministrationYYAllows us to create repositories on the user's behalf.
ChecksYYAllows us to add checks against source code on push.
ContentsYYAllows us to fetch and write source code for new project templates for the connected user or organization.
DeploymentsYYAllows us to synchronize deployment status between GitHub and the Vercel infrastructure.
Pull RequestsYYAllows us create deployments for each Pull Request (PR) and comment on those PR's with status updates.
IssuesYYAllows us to interact with Pull Requests as with the Pull Requests permissions due to GitHub requiring both for access.
MetadataYNAllows us to read basic repository metadata to provide a detailed dashboard.
Web HooksYYAllows us to react to various GitHub events.
Commit StatusesYYAllows us to synchronize commit status between GitHub and Vercel.

Organization permissions allow us to offer an enhanced experience through information about the connected organization.

PermissionReadWriteDescription
MembersYNAllows us to offer a better team onboarding experience.

User permissions allow us to offer an enhanced experience through information about the connected user.

PermissionReadWriteDescription
Email addressesYNAllows us to associate an email with a GitHub account.

We use the permissions above in order to provide you with the best possible deployment experience. If you have any questions or concerns about any of the permission scopes, please contact Vercel Support.

To sign up on Vercel with a different GitHub account, sign out of your current GitHub account.

Then, restart the Vercel signup process.

When importing or connecting a GitHub repository, we require that you have Collaborator access to the corresponding repository, so that we can configure a webhook and automatically deploy pushed commits.

If a repository is missing when you try to import or connect it, make sure that you have Collaborator access configured for the repository. For an organization or a team, this page explains how to view the permissions of the members. For personal GitHub accounts, this page explains how to manage access.

By default, comments from the Vercel GitHub bot will appear on your pull requests and commits. You can silence these comments in your project's settings:

  1. From the Vercel dashboard, select your project
  2. From the Settings tab, select Git
  3. Under Connected Git Repository, toggle the switches to your preference

If you had previously used the, now deprecated, github.silent property in your project configuration, we'll automatically adjust the setting for you.

It is currently not possible to prevent comments for specific branches.

You can use GitHub Actions to build and deploy your Vercel Application. This approach is necessary to enable Vercel with GitHub Enterprise Server (GHES) with Vercel, as GHES cannot use Vercel’s built-in Git integration.

  1. Create a GitHub Action to build your project and deploy it to Vercel. Make sure to install the Vercel CLI (npm install --global vercel@latest) and pull your environment variables vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
  2. Use vercel build to build your project inside GitHub Actions, without exposing your source code to Vercel
  3. Then use vercel deploy --prebuilt to skip the build step on Vercel and upload the previously generated .vercel/output folder from your GitHub Action to Vercel

You'll need to make GitHub Actions for preview (non-main pushes) and production (main pushes) deployments. Learn more about how to configure GitHub Actions and Vercel for custom CI/CD workflows.

Last updated on September 4, 2024