Covered in this doc

  • Installing Percy's GitHub integration
  • Linking Percy projects with GitHub repositories
  • Running and reviewing builds in GitHub

The Percy GitHub app will update the pull request summary if there are visual differences needing review, and will show which team member approved them. It will also help us provide smarter comparisons for you, by picking more relevant base builds.

Step 1: Install the Percy GitHub integration

Navigate to your Organization Settings > Integrations.


Click "Install" to add GitHub. On the next screen, when you click "Install App" you'll be directed to GitHub for authentication.


Note: GitHub requires that you have the "owner" role in an organization to add integrations.

You can install Percy to all repositories or select specific repositories.


By default, Percy will be installed with:

  • read access to code
  • read access to members, metadata, and pull requests
  • read and write access to commit statuses

Once installed, the next step is to link a Percy project to a GitHub repository.

Step 2: Link Percy projects and GitHub repositories

You can manage your linked repositories by selecting "Edit settings" under Organization Settings > Integrations.


You can also manage an individual project's linked repository. Head to your Project Settings and scroll to the "Link a repository" section.


Your repositories will automatically populate in the drop-down when you "Select a repository."

Step 3: Run and review builds


Make sure you have CI setup

Percy will need to run on each commit via CI for Percy's GitHub status check to show up.

Once you've added the app and linked projects with repositories, subsequent Percy builds will show metadata from GitHub and Percy will automatically update the pull request summary if there are visual differences waiting for review.


Note: By default, Percy approvals aren’t required before merging, but you can enable this feature once you’re ready for it.

Clicking "Details" will take you directly to the Percy build UI showing all visual diffs to be reviewed. Approving a build in Percy sets the Percy status in GitHub to green/successful, so that your team can see that any visual changes were reviewed and approved.


Step 4: Troubleshooting

If you find your integration is not working as expected, check the integration logs on the GitHub integration page. These can be found by selecting "Edit settings" under Organization Settings > Integrations.
The logs table will show you all the communication Percy has recently had with GitHub. If there is not a recent log line, you can click the "Run health check" button to create a new log from GitHub.


What's next

Learn about our additional workflow features like snapshot carryforward, auto-approved branches, baseline picking, and more.