Integrate Percy with AWS CodeBuild

Integrate Percy with AWS CodeBuild, a fully managed CI-CD service

Follow these steps to integrate Percy with AWS CodeBuild:

Configuring AWS CodeBuild 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 CodeBuild project, go to Edit > Environment > Additional configuration > Environment variables and add PERCY_TOKEN. For sensitive values, store the token in AWS Systems Manager Parameter Store or AWS Secrets Manager and reference it by type.

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

Commit, branch, and pull request information

Percy auto-detects AWS CodeBuild builds via the CODEBUILD_BUILD_ID environment variable and reads the following native CodeBuild variables:

• CODEBUILD_RESOLVED_SOURCE_VERSION — commit SHA.
• CODEBUILD_WEBHOOK_HEAD_REF — full git ref of the source branch in the form refs/heads/<branch> (for example, refs/heads/main). Percy strips the refs/heads/ prefix before using the value for PERCY_BRANCH. Set only when triggered by a webhook.
• CODEBUILD_WEBHOOK_TRIGGER — populated for pull request triggers in the form pr/<number> (for example, pr/42). Percy extracts the number for PERCY_PULL_REQUEST. Other webhook trigger types (branch/..., tag/...) do not populate the PR field.

If your build is not triggered via a webhook, branch and pull request data are not auto-populated. In that case, configure your environment to include 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

If you run multiple CodeBuild jobs in parallel as part of a single CI run (for example, via a batch build), PERCY_PARALLEL_TOTAL and PERCY_PARALLEL_NONCE need to be configured. Percy automatically uses CodeBuild’s CODEBUILD_BUILD_ID as the parallel build nonce. Set PERCY_PARALLEL_TOTAL to the total number of parallel builds.

Reference Topic

• Webhook Payloads