How to Configure Percy for a Pull Request Workflow

To run Percy visual checks on pull requests, store the project’s PERCY_TOKEN as a CI secret, run Percy alongside your tests or snapshot command, and connect the Percy project to the GitHub repository. Then verify a pull-request build is associated with the intended commit. Percy approvals do not block merges by default; make them required only if that is your team’s policy.

1. Create a Percy project and protect its token

Create or select the Percy project that will receive your visual builds, then copy its project-specific PERCY_TOKEN from project settings. BrowserStack describes this as a write-only token for submitting builds. Treat it as a credential: anyone who obtains it can submit builds to that project.

#	Preview	Product	Price
1		Modern GitLab DevOps Handbook: Migrate, Build, Secure, and Deploy with GitLab CI/CD (GitLab 16+ for...	$35.00	Buy on Amazon
2		Git: Project Management for Developers and DevOps - A Hands-on Guide to Version Control, Workflow...	$42.62	Buy on Amazon
3		CI/CD Engineering in Practice: Build Secure, Scalable Pipelines with GitHub Actions, GitLab CI/CD,...	$35.00	Buy on Amazon
4		THE DEVOPS ENGINEER'S HANDBOOK: Build, Deploy, and Monitor High-Scale Applications	$2.99	Buy on Amazon

For GitHub Actions, add it at Repository → Settings → Secrets and variables → Actions → New repository secret. Name the secret PERCY_TOKEN. Reference the secret in the workflow rather than placing the token in source code or a committed workflow file.

2. Choose how CI will create Percy snapshots

Use the invocation that matches the application and its existing test setup. Percy’s CI guidance supports running a test command under the Percy CLI, or submitting rendered pages or a directory of snapshots. Source-control integration alone does not create snapshots; a Percy command must run in CI.

#1 Best Overall

Modern GitLab DevOps Handbook: Migrate, Build, Secure, and Deploy with GitLab CI/CD (GitLab 16+ for Developers & DevOps Teams)

$35.00

Buy on Amazon

Run Percy with a test command

For a Cypress project configured with the appropriate Percy integration, the general workflow shape is:

npx percy exec -- cypress run

The precise SDK, installation command, and test-runner command depend on the project’s framework and installed Percy package. Use the framework-specific integration where required, and confirm that the Percy CLI can access the snapshots produced by the tests.

Submit a directory of rendered pages

If CI already generates static pages or another supported snapshot directory, install the CLI and submit that output. BrowserStack’s published GitHub Actions example uses this shape:

- uses: actions/checkout@v3
- uses: actions/setup-node@v3
  with:
    node-version: '14'
- run: npm install --save-dev @percy/cli
- run: npx percy snapshot _site/
  env:
    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

The action and Node versions above are examples from that published workflow, not a recommendation to pin a new project to those versions. Adapt the runtime, install command, and snapshot path to your repository’s supported versions and build output.

3. Add Percy to the pull-request workflow

Here is a minimal GitHub Actions job for submitting an existing generated snapshot directory. It assumes the project has a suitable build step that creates _site/; replace that step, path, and runtime with the project’s actual commands.

Rank #2

Sale

Git: Project Management for Developers and DevOps - A Hands-on Guide to Version Control, Workflow Management, and Using GitHub, GitLab, and Alternative Git Platforms (Rheinwerk Computing)

$42.62

Buy on Amazon

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 --save-dev @percy/cli
      - run: npx percy snapshot _site/
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

For test-driven capture, replace the build-and-snapshot steps with your project’s test command wrapped by percy exec -- and configure the framework integration as needed. Keep Percy in the same CI workflow that runs on pull-request commits. Percy’s GitHub guide says its status check appears when Percy runs on each commit.

For a team with parallel test suites, Percy supports uploading snapshots from separate processes or machines and rendering them in one build. Follow the supported parallelization setup for your CI architecture rather than treating independent uploads as unrelated builds.

4. Connect Percy to GitHub

1. Have a GitHub organization admin install the Percy GitHub integration. The current guide says GitHub organization ownership is required to add integrations.

   ×Worth Installing

   Windows Errors? Fix Them Before They Spread

   Outbyte PC Repair · freeRepair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallFix My PC Now →
   Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

2. Link the Percy project to the repository that runs the workflow. Check that you selected the repository the pull request actually targets.

3. Run the workflow on a pull-request commit, then open the resulting Percy build and check its repository, branch, commit, and pull-request association.

   Rank #3

   

   CI/CD Engineering in Practice: Build Secure, Scalable Pipelines with GitHub Actions, GitLab CI/CD, Jenkins, Docker, Kubernetes, and GitOps

   $35.00

   Buy on Amazon

When linked, Percy can correlate builds with commits and pull requests, surface visual-review status information, and provide a link from the pull request to the build. Other integrations are listed for GitHub Enterprise Server, GitLab, Bitbucket, and Azure DevOps; their configuration details vary by provider.

5. Decide whether visual approval should block merging

Percy approvals are not a merge prerequisite by default. Teams can choose to configure approval or status checks as merge blockers, but should do so deliberately: first agree on who reviews differences and how a build becomes approved, then configure the repository’s merge policy to match.

Baseline handling also affects review granularity. With the Git baseline model, reviewers approve or reject the full build. Visual Git allows approved snapshots to advance independently. Git is a fit for CI on feature branches; Visual Git is useful when the team wants to select snapshots independently.

6. Troubleshoot missing or incorrect pull-request results

• No Percy status appears: Verify that the GitHub integration is installed, the Percy project is linked to the intended repository, and Percy actually ran on the commit in CI. The GitHub status check depends on a Percy run for each commit.

• The build is attached to the wrong branch, commit, or pull request: Inspect the CI environment metadata. Percy clients can read branch, commit SHA, and pull-request information from the environment; some CI providers require explicit metadata wiring. Compare the metadata received by Percy with the commit that triggered the job.

  Rank #4

  Sale

  

  THE DEVOPS ENGINEER'S HANDBOOK: Build, Deploy, and Monitor High-Scale Applications

  $2.99

  Buy on Amazon

• The build is missing snapshots: Confirm the command matches the capture approach: test-driven runs need the appropriate framework integration, while directory submission needs the rendered output to exist at the supplied path before the snapshot command runs.

  ×

  Quick wins for a faster PC:

  Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →
  Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

• The token is rejected or builds go to the wrong project: Check that the CI secret is named and referenced correctly and that its value belongs to the intended Percy project. Keep it in the secret store; write-only does not mean harmless if exposed.

• A green check appears, but merging is still possible without approval: That is consistent with Percy’s default behavior. Decide whether the Percy check should be required by your repository’s merge policy and configure it accordingly.

• Parallel runs produce incomplete or separate results: Use Percy’s supported parallelization setup so uploads from the distinct processes or machines are rendered into the same build.

Or skip the browser setup

If your immediate need is a rendered-page screenshot rather than Percy’s pull-request visual-review workflow, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000.

See the ScreenshotNeo API documentation for options and setup. For example, this cURL request saves a screenshot 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

Sign up for ScreenshotNeo to get 1,000 free screenshots a month with no card.

Quick Recap

Bestseller No. 1

Modern GitLab DevOps Handbook: Migrate, Build, Secure, and Deploy with GitLab CI/CD (GitLab 16+ for Developers & DevOps Teams)

$35.00

SaleBestseller No. 2

Git: Project Management for Developers and DevOps - A Hands-on Guide to Version Control, Workflow Management, and Using GitHub, GitLab, and Alternative Git Platforms (Rheinwerk Computing)

$42.62

Bestseller No. 3

CI/CD Engineering in Practice: Build Secure, Scalable Pipelines with GitHub Actions, GitLab CI/CD, Jenkins, Docker, Kubernetes, and GitOps

$35.00

SaleBestseller No. 4

THE DEVOPS ENGINEER'S HANDBOOK: Build, Deploy, and Monitor High-Scale Applications

$2.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.