Ask the Community
Integrate Percy with Vercel
Integrate Percy with Vercel, a frontend cloud platform for static and dynamic web apps
Follow these steps to integrate Percy with Vercel:
Configuring Vercel environment variables
Start by configuring PERCY_TOKEN, our project-specific, write-only API token. It can be found in your Percy project settings.
In your Vercel project, go to Settings > Environment Variables and add PERCY_TOKEN. Enable Sensitive to keep the value hidden in build logs.
Enable system environment variable exposure.
From the Vercel dashboard, open your project, then go to Settings > Environment Variables > System Environment Variables and turn on Automatically expose System Environment Variables. Vercel only injects its system variables — VERCEL, VERCEL_GIT_COMMIT_SHA, VERCEL_GIT_COMMIT_REF, VERCEL_GIT_PULL_REQUEST_ID, and VERCEL_DEPLOYMENT_ID — into the build environment when this toggle is on. Without it, the build is not auto-detected and you must set PERCY_COMMIT, PERCY_BRANCH, and PERCY_PULL_REQUEST manually.
Alternatively, you can export the variable as part of your build script:
Commit, branch, and pull request information
Percy auto-detects Vercel builds via the VERCEL environment variable and reads the following native Vercel variables:
-
VERCEL_GIT_COMMIT_SHA— commit SHA -
VERCEL_GIT_COMMIT_REF— branch ref -
VERCEL_GIT_PULL_REQUEST_ID— pull request number (when the deployment is associated with a PR)
If any of these are not set in your environment, configure your environment to include PERCY_COMMIT, PERCY_BRANCH, and PERCY_PULL_REQUEST. See the environment variables docs page for more details.
Run your tests
With your environment configured, run your Percy snapshots via your test suite or another mechanism. Your Percy build will be created with the correct meta-data.
Parallelized build processes
For the vast majority of Vercel projects, set PERCY_PARALLEL_TOTAL=-1 in your Vercel environment variables. Vercel can re-trigger a build for the same deployment, which causes VERCEL_DEPLOYMENT_ID (used by Percy as the parallel build nonce) to repeat across runs and lead to 409 errors. Setting PERCY_PARALLEL_TOTAL=-1 disables parallel grouping and ensures each build is treated independently.
Set PERCY_PARALLEL_TOTAL=-1 for nonce stability.
Vercel can re-trigger a build for the same deployment, which would cause VERCEL_DEPLOYMENT_ID to repeat across runs and lead to 409 errors. To prevent unrelated builds from being grouped together, set PERCY_PARALLEL_TOTAL=-1 in your Vercel environment variables. This disables parallel grouping for the project and ensures each build is treated independently.
Advanced: group multiple parallel jobs into one build
Only if you genuinely run multiple parallel jobs that should be grouped into one Percy build, override the defaults: set PERCY_PARALLEL_TOTAL to the total number of jobs and PERCY_PARALLEL_NONCE to a value that is unique per CI run but shared across the parallel jobs.
Keep your Percy token secret.
Anyone with access to your Percy token can add builds to your project, though they cannot read data. If your code is public, do not commit the PERCY_TOKEN to your code.
Reference Topic
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!