Integrate Percy with GitHub
Integrate Percy with GitHub, a source code management tool
Percy now supports multiple GitHub integrations for our Enterprise customers. By installing these integrations, Percy’s GitHub app updates the pull request summary if there are visual differences needing review and shows which team member approved them.
Additionally, it enhances comparisons by selecting more relevant base builds, making your review process more efficient.
You must be an admin of your Percy organization to install integrations.
If you have two different organizations on BrowserStack and a single GitHub organization, use GitHub Enterprise Server.
The GitHub installation ID is unique, so keep in mind:
- Main organization integrations are accessible to sub-organizations. However, sub-organization integrations are not accessible to other sub-organizations.
- If a sub-organization has already added the GitHub application, it needs to remove it from its integrations. The application should be added to the main organization so that all its sub-organizations can access it.
- Organizations outside the same enterprise group cannot install the GitHub app on both organizations.
Follow the instructions for adding an integration:
Install the Percy GitHub integration
- Navigate to your Organization Settings > Integrations.
-
Click Install to add GitHub. This will take you to a new screen.
- Click Add Integration and then Install App which will direct you to GitHub for authentication.
GitHub requires that you have the “owner” role in a GitHub organization to add integrations.
You can install Percy on all repositories in the GitHub organization or select specific repositories if you prefer.
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 installation is complete, you’ll be redirected to the settings page for your new GitHub integration. You’ll also see that a link to it has been added to the sidebar on the left.
Link Percy projects and GitHub repositories
- Now that your Percy GitHub integration has been installed, you can link your Percy projects to your GitHub repos. Click the box reading Select a repository next to each Percy project you’d like to link to a GitHub repo to choose a repo for that project.
- If you prefer, you can also manage linked repositories individually for each project. Head to your Project Settings and scroll down to the Link a repository section.
Run and review builds
Once you’ve added the app, linked projects with repositories, and created a PR, ensure to trigger visual tests in your CI server to run alongside your integration tests. This ensures that subsequent Percy builds display metadata from GitHub. Percy automatically updates the GitHub pull request summary if there are visual differences waiting for review.
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.
Percy will need to run on each commit via CI for Percy’s GitHub status check to show up.
Troubleshooting
If you find your integration is not working as expected, check the integration logs on the page for that GitHub integration. Go to Organization > Integrations, and then click the Edit Settings button for the integration you need to troubleshoot.
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.
Next step
Learn about our additional workflow features like snapshot carryforward, auto-approved branches, baseline picking, and more.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!