GitHub

Install the Percy GitHub integration

1. Navigate to your Organization Settings > Integrations.

2. Click Install to add GitHub. This will take you to a new screen.

3. Click Add Integration and then Install App which will direct you to GitHub for authentication.

You can install App Percy on all repositories in the GitHub organization or select specific repositories if you prefer.

By default, App 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 App Percy projects and GitHub repositories

1. Now that your App Percy GitHub integration has been installed, you can link your App Percy projects to your GitHub repos. Click the box reading Select a repository next to each App Percy project you’d like to link to a GitHub repo to choose a repo for that project.
2. 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 installed your GitHub integration and linked projects with repositories, subsequent App Percy builds will show metadata from GitHub, and App Percy will automatically update the pull request summary if there are visual differences waiting for review.

By default, App 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 App Percy build UI showing all visual diffs to be reviewed. Approving a build in App Percy sets the App Percy status in GitHub to green/successful, so that your team can see that any visual changes were reviewed and approved.

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