Integrate Percy with Heroku CI

Integrate Percy with Heroku CI, Heroku’s continuous integration service

Follow these steps to integrate Percy with Heroku CI:

Configuring Heroku CI 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 Heroku app’s pipeline, go to Settings > Heroku CI > Test config vars and add PERCY_TOKEN. Heroku CI passes test config vars to test runs but keeps them out of your build logs.

Alternatively, you can export the variable as part of your build script:

Commit, branch, and pull request information

Percy auto-detects Heroku CI builds via the HEROKU_TEST_RUN_ID environment variable. Heroku CI also exposes:

• HEROKU_TEST_RUN_COMMIT_VERSION — commit SHA.
• HEROKU_TEST_RUN_BRANCH — branch name. Only populated when the test run is triggered through Heroku’s GitHub integration. Manual runs (Heroku dashboard, heroku ci:run, or API) do not set this variable; set PERCY_BRANCH explicitly in those cases.
• HEROKU_PR_NUMBER — pull request number (when the test run is associated with a PR).

If HEROKU_PR_NUMBER or HEROKU_TEST_RUN_BRANCH is not available in your environment, set PERCY_PULL_REQUEST and PERCY_BRANCH to populate those fields manually. 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

If you parallelize your build across multiple test runs, PERCY_PARALLEL_TOTAL and PERCY_PARALLEL_NONCE need to be configured. Percy automatically uses Heroku CI’s HEROKU_TEST_RUN_ID as the parallel build nonce. Set PERCY_PARALLEL_TOTAL to the total number of parallel runs.

Reference Topic

• Webhook Payloads