Introduction

Vercel Preview Deployments allow you to stage changes in a live environment before merging them to a production branch. This tutorial will guide you through configuring GitHub Actions to deploy pull requests (PRs) on Vercel automatically. Once deployed successfully, the Vercel bot will post the preview URL as a comment in the PR.

Prerequisites

1. Basic familiarity with Continuous Integration using GitHub Actions

Step-by-Step Guide

1. Create the GitHub Action Workflow

Let’s start by creating workflow file: .github/workflows/preview.yaml

name: GitHub Actions Vercel Preview Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

on:
  pull_request:

jobs:
  Deploy-Preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: amondnet/[email protected]
        with:
         vercel-token: ${{ secrets.VERCEL_TOKEN }}
         vercel-org-id: ${{ secrets.VERCEL_ORG_ID}}
         vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID}}
         github-comment: 'true'
         github-token: ${{ secrets.GITHUB_TOKEN }}
         scope: ${{ secrets.VERCEL_ORG_ID}}

2. Set Up Vercel CLI and Login

If you don’t have a Vercel account yet, you can create new one here.

npm i -g vercel
vercel login

3. Create new Vercel project

In your project directory, run vercel link to create a new project on Vercel. Answer the prompts based on your settings. If you're linking the project for the first time, your answer may be no to Link to existing project prompt:

? Set up “~/repos/demo-vercel-ci”? yes
? Which scope should contain your project? my projects
? Link to existing project? no
? What’s your project’s name? demo-vercel-ci
? In which directory is your code located? ./

After linking, a .vercel folder will be automatically added to your project's root directory and included in your .gitignore file.

project-root/
├── .github/
│   └── workflows/
│       └── preview.yaml
├── .vercel/
│   ├── project.json
│   └── README.txt
├── .gitignore

3. Configure GitHub Secrets

Next, we will configure the secrets required for the workflow. Inside the .vercel folder save the save the projectId and orgId from the project.json.

VERCEL_TOKEN=
VERCEL_ORG_ID=
VERCEL_PROJECT_ID=

To generate a Vercel token, navigate to the Account Settings page under your personal account dropdown on Vercel.

Create a new token, and save it as shown only once.

Let’s add repository secrets to GitHub. Go to Settings > Secrets and Variables > Actions > Repository Secrets and add secrets as shown below:

4. Set Workflow Permissions

To allow the Vercel bot to comment on PRs, go to https://github.com/OWNER/REPO/settings/actions. Under Workflow Permissions, select Read and Write permissions.

5. Push your changes

Commit and push your changes to open a pull request. GitHub Actions will then automatically deploy the preview to Vercel.

Source code

You can download the source code here

Resources

• https://vercel.com/guides/how-can-i-use-github-actions-with-vercel

• https://vercel.com/docs/deployments/preview-deployments#github-integration