GitLab
Integrate GitLab with Percy
For self-managed instances, see our GitLab self-managed documentation.
If you have two different organizations on BrowserStack and a single GitLab organization, use GitLab self-managed.
The GitLab installation ID is unique, so keep in mind:
- Main organization integrations are accessible to sub-organizations. However, sub-organization integrations are not accessible to other sub-organizations.
- If a sub-organization has already added the GitLab application, it needs to remove it from its integrations. The application should be added to the main organization so that all its sub-organizations can access it.
- Organizations outside the same enterprise group cannot install the GitLab app on both organizations.
Install the Percy GitLab.com integration
Create a GitLab Bot User
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.
- Go to https://gitlab.com/[orgname]/[project]/-/project_members
- 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.
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.
Run and review builds
Once you’ve added the app, linked projects with repositories, and created a PR, ensure to trigger visual tests in your CI server to run alongside your integration tests. This ensures that subsequent Percy builds display metadata from GitLab. Percy automatically updates the GitLab pull request summary if there are visual differences waiting for review.
Troubleshooting
If you find your integration is not working as expected, check the integration logs on the GitLab integration page. These can be found by selecting Edit settings under Organization Settings > Integrations.
The logs table will show you all the communication Percy has recently had with GitLab. If there is not a recent log line, you can click the Run health check button to create a new log from GitLab.
If you see that coverage visualization is breaking in MR because Gitlab takes it from the latest pipeline and the latest pipeline (from Percy) does not have coverage artifacts.
To resolve this, select merge request in the Gitlab Pipeline Type.
Next step
Learn about our additional workflow features like snapshot carryforward, auto-approved branches, baseline picking, and more.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!