How to Configure Percy for a Pull Request Workflow

To configure Percy for pull requests, store the Percy project token as a CI secret, run Percy in your pull request workflow, and link the Percy project to the GitHub repository. Then verify that each pull request commit creates a Percy build with the expected branch and commit. Percy approvals are not required before merging by default; make them a required check only if that is your team’s intended policy.

1. Create a Percy project and protect its token

1. Create or select the Percy project that will receive snapshots.
2. Copy that project’s PERCY_TOKEN from its settings.
3. In GitHub, open Settings → Secrets and variables → Actions, create a repository secret named PERCY_TOKEN, and paste the value.

The token is unique to a Percy project and permits build submission. Treat it as a credential: do not commit it, print it in workflow logs, or expose it to untrusted pull request code. For forked pull requests, GitHub does not make repository secrets available to the workflow by default. Keep token-using steps limited to trusted contexts and consult GitHub’s guidance before changing permissions or triggering privileged workflows.

2. Choose how Percy captures pages

There are two common approaches:

• Test-driven capture: use the Percy integration for your test framework and run the test command through Percy. This fits suites that navigate pages and capture states as tests run.
• Snapshot submission: render the site first, then submit a directory of static pages or snapshots. This fits static output such as a generated site directory.

Choose the invocation that matches the framework and artifacts your repository already produces. Install the Percy CLI or the relevant framework integration using the version and package manager conventions for your project. The examples below show the workflow shape; adapt the runtime, install command, and capture command to your repository.

3. Add Percy to GitHub Actions

Static site snapshot example

This example builds a site and submits its output directory. Replace npm run build and ./dist with the commands and output path used by your project.

name: Visual tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  percy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm ci
      - run: npm run build
      - run: npm install --no-save @percy/cli
      - run: npx percy snapshot ./dist
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Action and Node versions here follow the shape of Percy’s published example, not a recommendation to freeze a project on old versions. Use versions compatible with your project and current repository policy. Prefer a locked dependency and reproducible install strategy for production CI.

Test-driven example

For a Cypress project with the appropriate Percy SDK installed and configured, run the test suite through Percy:

- run: npx percy exec -- cypress run
  env:
    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

The precise package and command depend on the framework integration. Percy can also be started and stopped around test execution in CI; use the integration’s documented pattern rather than mixing lifecycle commands from different SDKs.

4. Link Percy with GitHub

1. Have an organization administrator install the Percy GitHub integration if the repository belongs to an organization.
2. Link the Percy project to the exact GitHub repository that runs the workflow.
3. Open a pull request or push a commit that triggers the workflow.
4. In Percy, confirm the resulting build is associated with the intended repository, branch, commit, and pull request.

The source control integration connects Percy builds with commits and pull requests and surfaces status information. The integration alone does not create visual snapshots: CI must run Percy on the commit. Percy documents GitHub Enterprise Server and other source control integrations too; setup details vary by provider.

5. Decide whether visual approval blocks merging

Percy’s default behavior does not require approvals before merging. A team can choose to configure visual approval as a required check, but first decide who reviews changes, what happens when a reviewer is unavailable, and whether a visual change should block urgent fixes. Verify the required status check in the repository’s branch protection or ruleset settings after a successful Percy run.

Also choose a baseline workflow. Percy’s Git build-level approval approves or rejects the build as a whole. Visual Git supports approving snapshots independently. Build-level review fits many feature-branch CI flows; snapshot-level selection can fit teams that want to advance approved pages separately.

6. Confirm the workflow works

• Open a pull request that runs the visual workflow.
• Check the Actions run completed and the Percy step received the token without printing it.
• Open the Percy build and verify repository, branch, commit, and PR association.
• Confirm snapshots represent the intended page states and the baseline is the expected one.
• Check the pull request for Percy’s status or link.
• If approval is meant to block merging, verify the check is configured as required and that an unapproved build prevents the expected merge path.

Configuration choices and edge cases

Choice	Use it when	Watch for
Run Percy with tests	Tests navigate to pages and capture meaningful application states.	Use the matching framework SDK and run command; a plain test run may not submit snapshots.
Submit a rendered directory	Your build produces static pages suitable for snapshotting.	Build the site first and point Percy at the actual output directory.
Non-blocking review	You want visual diffs visible without making them a merge gate.	A passing PR check does not mean someone approved the visual changes.
Required approval	Your team deliberately wants visual review before merge.	Configure the check in repository rules and account for emergency and reviewer workflows.
Git baseline	You want to approve or reject the complete build.	Review applies at build level.
Visual Git baseline	You want to advance selected snapshots independently.	Team members need to understand the snapshot-level baseline process.

For parallel test suites, Percy supports snapshots uploaded from separate processes or machines and rendered in one build. Use the supported parallelization setup for the SDK and CI architecture so workers contribute to the intended build rather than producing unrelated builds.

Troubleshooting

No Percy status appears on the pull request

Cause: The GitHub integration may not be installed, the Percy project may not be linked to this repository, or Percy did not run on the commit. Fix: Check the integration and project link, then confirm the workflow ran for the PR commit. Percy’s GitHub status check depends on Percy running on each commit through CI.

The workflow says the token is missing or authentication failed

Cause: The secret name is misspelled, the secret is configured at a different scope, or the event context does not expose repository secrets (a common case for forked pull requests). Fix: Confirm the secret is named PERCY_TOKEN, referenced in the Percy step’s environment, and available to that workflow event. Do not put the token directly in YAML as a workaround.

The Percy build is attached to the wrong branch or has no PR association

Cause: CI environment metadata may be missing or different from the expected provider values. Fix: Inspect the branch name, commit SHA, and pull request metadata available to the job. Follow Percy’s CI-specific metadata instructions if the provider or custom workflow needs explicit values.

The build exists but contains no useful snapshots

Cause: Percy was invoked without the intended test integration or the snapshot path points to the wrong build output. Fix: Confirm the capture command matches your chosen approach, the site was built before submission, and the target directory contains the expected pages. For test-driven capture, confirm the tests actually call the Percy capture API or use the supported integration.

Pull requests pass while visual changes remain unapproved

Cause: Percy approvals are non-blocking by default. Fix: If visual approval must gate merging, configure the relevant status check as required in your repository rules and validate the behavior with a PR.

Parallel workers create separate builds

Cause: Parallel processes are not using the integration’s supported shared-build configuration. Fix: Configure Percy’s documented parallelization mechanism for your CI setup and verify that all worker snapshots appear in the same build.

Performance, reliability, and cost considerations

Percy adds work to the CI job because pages or test states must be captured and uploaded. Keep the captured routes and states intentional, avoid running duplicate visual jobs for the same commit unless needed, and use your existing test and build outputs where possible. Parallelization can help distribute a large suite, but requires correct shared-build configuration.

For reliable PR results, run visual capture against the same commit being reviewed, keep branch and PR metadata intact, and make the token available only to trusted workflows. Decide whether a failed capture should fail the job and whether visual approval is a merge requirement; these are team policy choices. The research sources do not specify Percy pricing or a benchmark for runtime, so check current Percy plan details for your project rather than estimating costs from snapshot counts.

Or skip the browser setup

If your goal is to capture rendered pages rather than review code changes, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns an image or PDF. For example, capture a page as WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Equivalent Python and Node.js examples are in the ScreenshotNeo API documentation.

• Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; response headers say the page verdict and billing status.
• An MCP server lets AI agents, including Claude and Cursor, take screenshots.
• The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Sign up free for 1,000 screenshots a month, no card required.

FAQ

Does installing Percy’s GitHub integration create snapshots?

No. The integration connects builds to source control; your CI workflow still needs to run Percy and submit snapshots.

Can I use Percy with a provider other than GitHub?

Yes. Percy’s integration overview lists GitHub, GitHub Enterprise Server, GitLab, Bitbucket, and Azure DevOps variants. Follow the provider-specific setup for your repository.

Should every visual change block a pull request?

That depends on your review policy. Approval is not required by default, so configure a required check only when the team has agreed on the review and exception process.