Skip to main content

Set Environment Variables

Configure your environment variables to allow App Percy builds to run seamlessly.

App Percy is designed to integrate with your tests locally and with your CI environment. To establish this integration, set the PERCY_TOKEN environment variable by following these steps:


  • Keep your Percy token secret. Anyone with access to your token can consume your account quota.
  • The “write-only” token can only be used to make changes, not to view your data.
    A Percy token is generated when you create a App Percy project. The token is a write-only API key that is unique for each project. You can find this on the Project Settings page. Percy Token

  2. Set PERCY_TOKEN as environment variable
    You can run App Percy:

    To learn about how to set your Percy token as an environment variable, see the relevant section.

App Percy works best when triggered automatically from your CI environment, but can also be run from your local development environment. This is helpful during the initial integration of App Percy.

Run App Percy locally

To run App Percy locally, set the PERCY_TOKEN environment variable using the export keyword as shown:

Copy icon Copy snippet

Alternatively, you can set the PERCY_TOKEN environment variable locally using the export keyword in a single line:

Copy icon Copy snippet


  • When running in your local environment, it is recommended to set the PERCY_BRANCH environment variable to “local” to prevent unintentionally overwriting of your project’s master baseline in App Percy. While not compulsory, this measure ensures the preservation of any baselines established by CI.
  • If you don’t use the PERCY_BRANCH variable while you run local tests and you happen to be on the master branch, then it will result in setting the baseline for your project in App Percy as the master branch.

Run tests in parallel on BrowserStack App Infra

If you are using BrowserStack (App Automate) for your mobile device infra with Percy, then you can run multiple tests at the same time across various devices. This is called parallel testing. Parallel testing gives you the same benefits as running a multi-threaded application. More parallel tests speed up the time taken to complete a test suite.

BrowserStack App Automate plan supports running the number of parallel tests (5 during free trial). You can purchase more parallel as per your need. To learn more about parallel testing on Browserstack infra, visit here.

Run from your CI setup

To run App Percy from your CI workflow, update both the CI configuration file and the pipeline script. Learn more.

App Percy works best when integrated into your CI workflow, running continuously alongside your test suite. It seamlessly integrates with major CI providers and offers configurability for custom environments.

We recommend to run App Percy via your CI workflow.

Other supported parameters

App Percy client libraries retrieve additional details from the environment they are running in, including the branch name, commit SHA, GitHub Pull Request number, and more. You can modify certain aspects of App Percy’s behavior by configuring these environment variables within your CI environment:

Environment Variable Description
PERCY_BRANCH The branch in which the build is being executed. Default is the current git branch.
PERCY_TARGET_BRANCH The branch for comparison. Default set to master. \n- If the App 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. To know more, read base build docs.
PERCY_TARGET_COMMIT The full commit SHA of an existing App Percy build to be used as the reference baseline. To know more, read base build docs.
PERCY_PULL_REQUEST The pull request number to link with the build, if any.
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 App Percy running in your CI environment. This can be useful to set conditionally if you want App Percy to be disabled in certain scenarios.
PERCY_DEBUG Set to true to debug asset discovery and do not upload snapshots.
PERCY_LOGLEVEL Set it to any of the following: ‘info’, ‘silent’, ‘warn’ or ‘debug’.
PERCY_TMP_DIR Set an absolute path accessible locally where screenshots will be stored.

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.

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

Is this page helping you?


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!

Talk to an Expert
Download Copy