Set up preview deployments for pull requests using CircleCI and Vercel

Working in front-end development involves writing features and bug fixes in different branches. But how do you ensure that reviewers, testers, and other stakeholders find it easy to view changes? Using preview deployments is one solution.

Preview deployments allow you to automatically create a live URL each time someone opens a pull request (PR). It’s like giving every branch its mini website so that changes can be tested and proven in isolation. You can review your changes before you commit them to the main branch.

Using Vercel and CircleCI, you’ll learn how to set up preview deployments for your React app in this guide. We’ll take you through each process step-by-step, from linking your repo to Vercel to setting up CircleCI to deploy new pull requests.

Prerequisites

• A GitHub repository with a frontend project
• A Vercel account linked to GitHub
• A CircleCI account linked to the same GitHub repository
• Basic knowledge of CI/CD pipelines

Why use preview deployments for your PR?

So let’s assume you are on a new feature. You push your code to another branch and make a pull request. By default, your reviewers will look directly at your code or pull the branch to run it locally. That’s not necessarily easy or fast.

With preview deployments, your PR will have its live link automatically. This is a lot of benefits;

• Instant visual feedback: Reviewers can use the link and view the feature propagate, without actually running the code.

• Safe testing environments: There is a unique sandbox for each PR, which means no more testing on production or staging servers.

• Faster, better code reviews: Design teams, QA, and even non-dev stakeholders can review UI without any technical setup.

• Confidence before merge: Because each PR is isolated, bugs or design problems are noticed earlier and in context.

For instance, in this guide when we push a PR to our frontend repo, a unique link will be generated automatically: https://preview-deploy-demo-circle-ci-[branch-name].vercel.app.

This workflow makes collaboration a lot less painless. It reduces the “it worked on my machine” issue at the end of the day, helping your team ship more confidently.

Set up your project on Vercel

To start preview deployments, connect your frontend project to Vercel. The service will generate a live preview link each time you push a pull request (PR). Here’s what you need to do:

Push your frontend codes into GitHub

Upload your front-end application to GitHub first. This can be a simple React app or any other front-end project you’re working on. An important thing to keep in mind is that your project should be built correctly with a framework backed by Vercel, such as React, Next.js, or Vue.

If you need inspiration, here’s a sample project, used for this guide:

Log into Vercel to import the project

Go to vercel.com and log in using your GitHub profile. Click Add New Project for a list of your GitHub repositories.

From the list of options, click your front-end repo to import it into Vercel.

Configure your Vercel project

Vercel will automatically know your framework. If you’re using React (as with the demo project), it should select Create React App. You can leave the defaults: confirm the project name and click Deploy.

After deployment, Vercel will give you a live production link. But during preview deployment, this won’t be the one used. Rather, in making pull requests, preview links will be created and you’ll get to do that soon when integrating with CircleCI.

Connect your GitHub project to CircleCI

Now that your React project is live on GitHub and deployed to Vercel, it is time to create an association between the same project and CircleCI. This makes CircleCI monitor your project for new pull requests and automatically perform a preview deployment using your CI pipeline.

In this section, you’ll connect your GitHub repo to Circle CI and commit a starter configuration file.

Step 1: Log into CircleCI

First, log into CircleCI. If you have an account with GitHub, select Continue with GitHub. CircleCI will request access to your GitHub to read your repositories and manage builds based on your code changes.

For some accounts, there is a possibility that GitHub will not automatically connect upon logging in. If you don’t see your GitHub repositories listed, you can manually connect GitHub by going to your CircleCI Organization Settings. You’ll find this if you click the gear icon at the bottom left of the dashboard. From there move to the VCS (Version Control System) section. Under the GitHub heading, click Install CircleCI GitHub App and authorize the integration when the message pops up.

Afterward, go back into your CircleCI dashboard and refresh the page. Once you connect successfully with GitHub, your repositories will show up under the Projects tab. Now you can start building your project in CircleCI.

Step 2: Set up the project on CircleCI

1. In the CircleCI dashboard, click “Projects” in the sidebar.

2. On the next page, you will be prompted to import your project directly. Find your repository (preview-deploy-demo-circleci for the sample project) and click Set Up Project.

3. Since the .circleci/config.yml file is already committed to the main branch of your repository, CircleCI will detect it automatically. Select the main branch if prompted, and click Set Up Project to proceed.

4. CircleCI will start a pipeline using the existing config file. Monitor the pipeline on the dashboard to ensure it runs successfully.

Step 3: Verify the pipeline runs

When everything is in place, CircleCI will trigger a pipeline based on the content of the .circleci/config.yml in your main branch. Go to CircleCI dashboard, select your project (preview-deploy-demo-circleci) and check to see if the pipeline is running. If the pipeline doesn’t start automatically, do a minor change to your repository (such as changing your README). Then, push it to main and the pipeline will execute.

Set up preview deployments in Vercel

It’s time to link your Vercel account. It will deploy your app automatically when you open a pull request now that your CircleCI pipeline is set up. That’s what provides you with a preview URL for each branch: a live link you can use to review changes before merging to main.

Step 1: Add your Vercel token to CircleCI

To deploy using Vercel from CircleCI you’ll need an access token. This lets CircleCI log in to your Vercel account.

1. Find yourself on Vercel Tokens when you are logged in at Vercel.

2. Click “create,” name it “CircleCI Preview,” and copy the generated token.

Note: If you’re in various organizations on Vercel, you have to add a unique scope to make sure the token is set up under the correct place. Because tokens are scoped to your organization, using the wrong one could give you the wrong permissions or deploy code to a different team.

1. Visit CircleCI Project Settings, click your project, then go to “Environment Variables.”

2. Add a new variable:

• Name: VERCEL_TOKEN
• Value: Paste the token you copied

This securely exposes the token to CircleCI builds with out exposing it to your code.

Step 2: Configure triggers in CircleCI project settings

You’ll need to set up a trigger for your project in the CircleCI dashboard. This ensures that your preview deployment only runs for pull requests. Next steps:

• Go to your project on CircleCI and click on the settings.
• Navigate to “Triggers” from the settings.
• Tap on the pencil icon at the side of the existing trigger to edit.
• On the next page, you need to set the trigger to PR opened under the Run on option.

Step 3: Verify the deployment setup

With the Vercel token added to CircleCI, your existing .circleci/config.yml is ready to deploy your app automatically when a pull request is opened. The deploy job will use the token to authenticate with Vercel and generate a preview URL for each branch.

Test the workflow

Your CircleCI configuration is already set up in the .circleci/config.yml file on the main branch, with a workflow that triggers for pull requests. Review the config before testing:

version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:18.17.0
    environment:
      BROWSERSLIST_IGNORE_OLD_DATA: true
    steps:
      - checkout
      - run: npm install
      - run: npm run build
      - run:
          name: Install Vercel CLI
          command: sudo npm install -g vercel
      - run:
          name: Deploy to Vercel
          command: vercel --token $VERCEL_TOKEN --prod=false --confirm

workflows:
  deploy_on_pr:
    jobs:
      - deploy

The above .circleci/config.yml file mentions what CircleCI is supposed to do each time you push code or open a pull request. For this case, it uses a Node.js environment to do the following:

1. Check out your code from GitHub.

2. Install project dependencies by npm install.

3. Build the project with npm run build.

The BROWSERSLIST_IGNORE_OLD_DATA: true environment variable prevents the build process from checking for changes in the browser list, which is perfect for CI use. With the deploy_on_pr workflow, as soon as a pull request is either opened or updated, CircleCI will run this workflow if the GitHub integration is set up correctly.

Once everything is configured, it’s time to test your preview deployment setup. Begin by making a small, visible change in your project by creating a new branch and changing certain code. For example, you can edit the text in App.js from “Hello from Preview Deploy App” to “Hello from the PR Branch!.” Push your branch onto GitHub and open a pull request (PR) to your main branch.

When the PR is opened, CircleCI will automatically run the configured workflow. It is possible to watch the build on your CircleCI dashboard. The deploy job should be executed under your PR pipeline using the Vercel CLI and $VERCEL_TOKEN to deploy a preview.

After deployment, Vercel will give a unique preview URL; for example: https://preview-deploy-demo-git-08207b-john-abrahams-projects-f2ca632e.vercel.app/. This helps you to review the PR changes live.

![Preview deployment for pull request on Vercel]2025-05-13-pull-request-preview-vercel.jpg

Reviewers and teammates can use the link to review the changes in a live environment before merging. This helps your team to easily spot problems where they occur. It prevents issues from getting lost while reviewing changes visually. This makes your pull request workflow more efficient and secure.

Conclusion

Preview deployments can improve your workflow. They let you and your team see new changes before they get to production. By connecting CircleCI and Vercel, you can automatically deploy changes from a pull request. This allows quicker feedback, visual testing, and more secure code reviews.

In this guide, you learned how to set up your GitHub repository with Vercel. You also learned to set up CircleCI with adequate configuration and linked deployments to pull request events. To keep secrets safe, you also learned to use environment variables. These allow deployments to only occur when the conditions are perfect.

If you work with a team, you may want to expand your workflow. You can add preview URLs in the form of comments in pull requests. Or add labels saying “ready for review.” This is easy for collaborators and reviewers to access and confirm changes before merging. Now that you’ve set up your preview pipeline, you’re ready to ship confidently. Every update gets the review and testing it needs before turning live.