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.
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.
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."
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.
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.
Updated 9 months ago