Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2!

GitHub

Integrating GitHub with Percy to incorporate visual reviews into your current code review process.

The Percy GitHub app will automatically 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.

Installing the Percy GitHub integration


Navigate to your Organization Settings > Integrations and click "Install" to add GitHub. 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.

Syncing Percy projects and GitHub repositories


Head to your Project Settings and scroll to the "Link a repository" section. Your repositories will automatically populate in the drop-down.

Once you've added the app and linked projects with repositories, 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.

Additional information