GitHub

📘

Multiple GitHub integrations available for Percy Enterprise

Percy now supports multiple integrations for our Enterprise customers. To install additional GitHub integrations, follow the instructions below for adding an integration.

👍

Covered in this doc

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

Percy's 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.

🚧

Percy admin access required

You must be an admin of your Percy organization to install integrations.

Step 1: 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 permissions

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.

Step 2: 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.

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 installed your GitHub integration 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 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.