Environment variables


Covered in this doc

List of required and optional environment variables


For authentication, Percy requires a token environment variables to be set:

  • PERCY_TOKEN: The Percy repo write-only API token. This is unique for each Percy repository.

You can find PERCY_TOKEN in your project settings.



IMPORTANT: Keep your Percy token secret. Anyone with access to your token can consume your account quota. They will not be able to read data because the token is write-only.

See the Setup guides for how to securely set environment variables in your CI service.


Percy client libraries pull other information from the environment they are running in, such as the branch name, commit SHA, GitHub Pull Request number, etc. You can override some of Percy's behaviors by setting these environment variables in your CI environment:

  • PERCY_BRANCH: The branch the build is being run in. Defaults to the current git branch.
  • PERCY_TARGET_BRANCH: The branch to compare against. Defaults to master.
    • If the Percy build is associated to a GitHub Pull Request, setting this value will have no effect and the target branch will be automatically determined from the GitHub PR.
    • For more context, see our base build docs
  • PERCY_TARGET_COMMIT: The full commit SHA of an existing Percy build to be used as the baseline.
  • PERCY_COMMIT: The commit SHA to associate to the build.
  • PERCY_PULL_REQUEST: The pull request number to associate to the build, if any.
  • PERCY_PARALLEL_TOTAL: The total number of parallel builds to expect.
    • In most setups this is automatically discovered and does not need to be set. See Parallel test suites for more info.
  • PERCY_PARALLEL_NONCE: A unique identifier used to group parallel builds. This can be any string that is shared between parallel runners, such as the CI build number.
    • In most setups this is automatically discovered and does not need to be set. See Parallel test suites for more info.
  • PERCY_PARTIAL_BUILD: Set to 1 to indicate the build is a partial build, and that it intentionally will be a subset of the snapshots from a full build.
  • PERCY_ENABLE: Set to 0 to prevent Percy running in your CI environment. This can be useful to set conditionally if you want Percy to be disabled in certain scenarios.
  • PERCY_DEBUG: Set to true to debug asset discovery and do not upload snapshots
  • PERCY_LOGLEVEL: Set to one of 'info', 'silent', 'warn' or 'debug'


With the latest version of @percy/agent, any of the environment variables defined on this page can be specified within a .env file in current working directory.

What's next

See the CI setup docs to see how to set environment variables in your CI service or in local development environments.