Deploying GitHub Projects with Vercel

Vercel for GitHub automatically deploys your GitHub projects withVercel, providingPreview Deployment URLs, and automaticCustom Domain updates.

• GitHub Free
• GitHub Team
• GitHub Enterprise Cloud
• GitHub Enterprise Server (When used with GitHub Actions)

TheDeploying 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 theGit section in the Project Settings.

Vercel for GitHub willdeploy every push by default. This includespushes and pull requests made to branches. This allows those working within therepository 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 thegithub.autoJobCancellation option in yourvercel.json file.

IfCustom Domains are set from a project domains dashboard, pushes and merges to theProduction 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 previousProduction Deployment from a commit will automatically be made available at theCustom Domain instantly; providing you with instant rollbacks.

The latest push to any pull request will automatically be made available at a uniquepreview 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 thevercel.json file or the Project hasEnvironment Variables, Vercel will require authorization from you or aTeam Member to deploy the pull request.

This behavior protects you from leaking sensitive Project information.

You can disableGit 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 theSlack 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 throughGitHub's checks. Vercel will provide the deployment URL to the checks that require it, for example; to a testing suite such asCheckly.

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

You may want to use different workflows and APIs based on Git information. To support this, the followingSystem Environment Variables are exposed to your Deployments:

VERCEL_GIT_REPO_SLUG=my-site

VERCEL_GIT_REPO_OWNER=acme

VERCEL_GIT_REPO_ID=117716146

VERCEL_GIT_COMMIT_REF=improve-about-page

VERCEL_GIT_COMMIT_SHA=fa1eade47b73733d6312d5abfad33ce9e4068081

VERCEL_GIT_COMMIT_MESSAGE=Update about page

VERCEL_GIT_COMMIT_AUTHOR_LOGIN=johndoe

VERCEL_GIT_COMMIT_AUTHOR_NAME=John Doe

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.

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

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

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

Then, restart the Vercelsignup process.

When importing or connecting a GitHub repository, we require that you haveCollaborator 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 haveCollaborator access configured for the repository. For an organization or a team, thispage explains how to view the permissions of the members. For personal GitHub accounts, thispage 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 Verceldashboard, select your project
2. From theSettings tab, selectGit
3. UnderConnected 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.

By default, Vercel notifies GitHub of deployments usingthedeployment_status webhook event. This creates an entry in the activity log of GitHub's pull request UI.

Because Vercel also adds a comment to the pull request with a link to the deployment, unwanted noise can accumulate from the list of deployment notifications added to a pull request.

You can disabledeployment_status events by:

• Going to the Git settings for your project
• Disabling thedeployment_status Events toggle

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 variablesvercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
2. Usevercel build to build your project inside GitHub Actions, without exposing your source code to Vercel
3. Then usevercel 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.

Vercel sendsrepository_dispatch events to GitHub when the status of your deployment changes. These events can trigger GitHub Actions, enabling continuous integration tasks dependent on Vercel deployments.

GitHub Actions can trigger on the following events:

on:repository_dispatch:    -'vercel.deployment.success'    -'vercel.deployment.error'    -'vercel.deployment.canceled'    -'vercel.deployment.ignored'    -'vercel.deployment.skipped'    -'vercel.deployment.pending'    -'vercel.deployment.failed'    -'vercel.deployment.promoted'

repository_dispatch events contain a JSON payload with information about the deployment, such as deploymenturl and deploymentenvironment. GitHub Actions can access this payload throughgithub.event.client_payload. For example, accessing the URL of your triggering deployment throughgithub.event.client_payload.url.

Read more and see thefull schema inourrepository-dispatch package, and see thehow can I run end-to-end tests after my Vercel preview deployment? guide for a practical example.

Withrepository_dispatch, the dispatch eventclient_payload contains details about your deployment allowing you to reduce GitHub Actions costs and complexity in your workflows.

For example, to migrate the GitHub Actions trigger for preview deployments for end-to-end tests:

Previously, we needed to check if the status of a deployment was successful. Now, withrepository_dispatch we can trigger our workflow only on a successful deployment by specifying the'vercel.deployment.success' dispatch type.

Since we're no longer using thedeployment_status event, we need to get theurl from thevercel.deployment.success event'sclient_payload.

name: End to End Testson:- deployment_status:+ repository_dispatch:+   types:+    - 'vercel.deployment.success'jobs:  run-e2es:-   if: github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success'+   if: github.event_name == 'repository_dispatch'    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Install dependencies        run: npm ci && npx playwright install --with-deps      - name: Run tests        run: npx playwright test        env:-         BASE_URL: ${{ github.event.deployment_status.environment_url }}+         BASE_URL: ${{ github.event.client_payload.url }}