Sign in or start for free
Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

**This doc will walk you through integrating Percy with your GitLab Self-Managed instance. For GitLab.com, see our [GitLab.com documentation](🔗).**

**Note:** If you are running GitLab Self-Managed **behind a firewall**, fill out the form at the bottom of this page and we'll be in touch shortly.

# 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 on in your GitLab 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:

1258


The end result should look like this:

1269


# 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:

658


# Add the Personal Access Token and GitLab Host to Percy

You’re ready to add your GitLab details to Percy. Go to your organization Settings > Integrations and paste the personal access token and GitLab Host into the form field.

1256


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

# Connect Your Projects to Repositories

Go to the project settings page for the project you wish to integrate and connect a GitLab repo:

682


Done! 🚀 You’re ready to start running visual testing alongside code reviews. The next step is to integrate with your CI service to leverage your existing test pipeline and kick off visual tests automatically.

To configure GitLab CI, see the [GitLab CI docs page](🔗). If you’re using another CI service, see the appropriate docs:

  • [Travis CI](🔗)

  • [CircleCI](🔗)

  • [Semaphore](🔗)

  • [Codeship](🔗)

  • [Buildkite](🔗)

  • [Drone](🔗)

  • [Jenkins](🔗)

  • [Local development](🔗)

# Support for GitLab Self-Managed behind a firewall

If you are running GitLab Self-Managed behind a firewall, fill out the form below and we'll be in touch shortly.

(Script tags will be stripped)