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!

GitLab.com

Integrating GitLab with Percy

Covered in this doc

Installing Percy's GitLab.com integration
Linking Percy projects with GitLab repositories

For self-managed instances, see our GitLab self-managed documentation.

Step 1: Install the Percy GitLab.com integration


Create a GitLab Bot User

Note: Percy uses a personal access token to update commit statuses on GitLab. These API calls are made on behalf of a GitLab user that you specify when you generate a personal access token. You may wish to create a separate GitLab user that has access to only the GitLab projects you wish to integrate with Percy. This allows you to restrict the scope of the API access you provide us and make it clear to your organization how commit statuses are being set.

Create a new user in your GitLab.com organization. We recommend calling it “Percy,” so it’s easily identified.

In GitLab, go to the project you want to integrate Percy with and grant your bot user “Developer” access to it.

  1. Go to https://gitlab.com/<orgname>/<project>/project_members
  2. Grant the bot user you created above with access to your projects using the role “developer,” like this:

The end result should look like this:

Generate a Personal Access Token

Once you have created a bot user and invited them to the GitLab project you intend to use with Percy, generate a personal access token with the following values:

Add the Personal Access Token to Percy

You’re ready to add that access token to Percy. Go to your Organization Settings > Integrations and click to install the GitLab.com integration. Paste the personal access token into the form field.

You’ve now installed the GitLab integration! The next step is to link GitLab repositories to your Percy projects.

Step 2: Link Percy projects to GitLab repositories


You can manage your linked repositories by editing the settings for the GitLab.com integration 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.

Step 3: Run and review builds


Once you've added the app and linked projects with repositories, subsequent Percy builds will show metadata from GitLab, and the Percy status will be shown on GitLab merge requests.


What's next

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

Approval workflows
Base build selection

GitLab.com


Integrating GitLab with Percy

Suggested Edits are limited on API Reference Pages

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