👍

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 GitHub 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.


What's next

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