You can use Vercel with CircleCI as your CI/CD provider to generate Preview Deployments for every
git push and deploy to Production when code is merged into the
This approach is useful for developers who want full control over their CI/CD pipeline, or those who can't leverage Vercel's built-in git integration. This guide will help you get started using CircleCI with Vercel.
Building Your Application
You can build your application locally (or in CircleCI) without giving Vercel access to the source code through
vercel build. Vercel automatically detects your frontend framework and generates a
.vercel/output folder conforming to the Build Output API specification.
vercel build allows you to build your project within your own CI setup, whether it be CircleCI or your own in-house CI, and upload only those build artifacts (and not the source code) to Vercel to create a deployment.
Configuring CircleCI for Vercel
vercel deploy --prebuilt skips the build step on Vercel and uploads the previously generated
.vercel/output folder from CircleCI. Let's define our jobs in
1version: 2.12jobs:3preview_deployment:4docker:5- image: circleci/node:latest6environment:7VERCEL_ORG_ID: $VERCEL_ORG_ID8VERCEL_PROJECT_ID: $VERCEL_PROJECT_ID9steps:10- checkout11- run:12name: Install Vercel CLI13command: npm install --global vercel@latest14- run:15name: Pull Vercel Environment Information16command: vercel pull --yes --environment=preview --token=$VERCEL_TOKEN17- run:18name: Build Project Artifacts19command: vercel build --token=$VERCEL_TOKEN20- run:21name: Deploy Project Artifacts to Vercel22command: vercel deploy --prebuilt --token=$VERCEL_TOKEN2324production_deployment:25docker:26- image: circleci/node:latest27environment:28VERCEL_ORG_ID: $VERCEL_ORG_ID29VERCEL_PROJECT_ID: $VERCEL_PROJECT_ID30steps:31- checkout32- run:33name: Install Vercel CLI34command: npm install --global vercel@latest35- run:36name: Pull Vercel Environment Information37command: vercel pull --yes --environment=production --token=$VERCEL_TOKEN38- run:39name: Build Project Artifacts40command: vercel build --prod --token=$VERCEL_TOKEN41- run:42name: Deploy Project Artifacts to Vercel43command: vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN4445workflows:46version: 247preview_and_production:48jobs:49- preview_deployment:50filters:51branches:52ignore: /main/53- production_deployment:54filters:55branches:56only: /main/
preview_deployment job will run when your code is pushed to a git branch other than
main, and the
production_deployment job will run when code is merged into the
Next, add the required values from Vercel as environment variables in CircleCI:
- Retrieve your Vercel Access Token
- Install the Vercel CLI and run
- Inside your folder, run
vercel linkto create a new Vercel project
- Inside the generated
.vercelfolder, save the
- In CircleCI, add
VERCEL_PROJECT_IDas Environment Variables
Deploying Your Vercel Application with CircleCI
Now that your Vercel application is configured with CircleCI, you can try out the workflow:
- Create a new pull request to your repository
- CircleCI will recognize the change and use the Vercel CLI to build your application
- The job uploads the build output to Vercel and creates a Preview Deployment
- When the pull request is merged, a Production build is created and deployed
Every pull request will now automatically have a Preview Deployment attached. If the pull request needs to be rolled back, you can revert and merge the PR and Vercel will start a new Production build back to the old git state.