Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

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.

Step 1: Install the Percy GitHub integration


Navigate to your Organization Settings > Integrations.

Click "Install" to add GitHub. On the next screen, 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.

Step 2: Link Percy projects and GitHub repositories


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

Step 3: Run and review builds


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.


What's next

Learn about our additional workflow features like snapshot carryforward, auto-approved branches, baseline picking, and more.

Approval workflows
Base build selection

GitHub


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.