Skip to main content
Connect a GitLab group to back Peeps projects with GitLab repositories. Your repository holds the tests and runs them in GitLab CI/CD. Peeps reports, analyzes, heals and generates tests, and proposes changes as merge requests. On GitHub you install the Peeps GitHub App. On GitLab you give Peeps an access token instead. You connect, replace and disconnect it in Peeps. One connection covers every project in the group and its subgroups, and an organization connects one group. It works with gitlab.com and with self-managed GitLab.

​
Create an access token

Use a group access token if your plan has them: gitlab.com Premium or Ultimate (not a trial), or any self-managed GitLab. On gitlab.com Free, use a personal access token instead.
1

Open the group's access tokens

In GitLab, open the group that holds your test projects, then Settings > Access tokens. Click Add new token.
2

Choose the role and scope

Set Role to Maintainer and select the api scope.
Peeps uses the token to read the repository, start pipelines, open merge requests, post commit statuses, push fix branches and add its project webhook. Adding a webhook needs the Maintainer role. GitLab requires an expiry date, up to a year away. Any date works: Peeps rotates the token for you two weeks before it expires (see Token rotation).

​
Connect the group

1

Open GitLab settings in Peeps

In Peeps, open Settings and select GitLab under Organization.
2

Enter the group and token

Enter the Group path, such as my-company or my-company/qa, and the Access token. Click Connect GitLab. On self-managed GitLab, first click Using self-managed GitLab? and enter your instance’s address.Peeps checks the token with GitLab before saving it, and stores it encrypted.
The connection then appears on the GitLab settings page. It shows its instance, the token’s scopes and expiry, and how many projects use it.

​
Connect a project

1

Open the project's repository settings

Open the Peeps project you want to back with GitLab, then Settings > Repository. Only an empty project can be connected.
2

Choose GitLab and the project

Select GitLab, pick the connection, then pick the GitLab project. Peeps suggests the Test root and Playwright config from the repository. Change them if they’re wrong.
3

Connect

Click Connect GitLab project. Peeps reads the repository’s tests and adds its webhook to the project, so pushes, comments and pipelines reach Peeps.

​
Add the Peeps job to your CI configuration

Once the project is connected, its Repository settings page shows the CI job to add. Copy it into your .gitlab-ci.yml. The job:
  • runs when Peeps starts a pipeline, on merge request pipelines, and on pushes to your default branch
  • authenticates to Peeps with a GitLab ID token, so your project stores no Peeps secret
Peeps starts pipelines with the PEEPS_MODE and PEEPS_SESSION_ID variables. New gitlab.com projects allow no one to set pipeline variables, which stops Peeps starting runs. When that’s the case, the project’s Repository settings page in Peeps says so and offers Allow Peeps to start pipelines, which sets Minimum role to use pipeline variables to Maintainer. You can also change it yourself in GitLab under Settings > CI/CD > Variables.

​
Commands in issues and merge requests

Comment /peeps heal, /peeps run, /peeps generate or /peeps inventory on an issue or merge request. Peeps reacts to the comment, does the work, and replies in the same thread. Only project members with the Developer role or higher can run commands.

​
Manage the connection

The GitLab page in Peeps settings lists every connection.
  • Replace token. Paste a new token for the same group, for example after automatic rotation failed. Projects keep working while you swap it. Revoke the old token in GitLab afterwards.
  • Webhook. Shows the webhook URL and secret token. If Peeps could not add its webhook, for example because the token lacked the Maintainer role, add it in the GitLab project under Settings > Webhooks. Choose push, comment, pipeline and merge request events. Re-check permissions on a project’s Repository settings page also adds the webhook back if it’s missing.
  • Disconnect. Removes Peeps’ webhooks from the group’s projects and deletes the stored token. Disconnect first if you want to connect a different group. Connected projects keep their tests and history, but stop syncing, running and healing. Connecting the group again picks them back up. The token stays valid in GitLab until you revoke it there.

​
Token rotation

GitLab access tokens expire. Two weeks before the connection’s token does, Peeps asks GitLab to rotate it: GitLab revokes the old token and issues a new one with the same role and scope, which Peeps stores in its place. Peeps asks for the longest lifetime your GitLab instance allows. You do nothing. The GitLab page shows when the token last rotated and when it next will. If GitLab refuses a rotation, Peeps tries again the next day, and the GitLab page says why it was refused. Older self-managed GitLab versions can’t rotate a token this way; the page says so, and you replace the token yourself before it expires. If Peeps can’t tell whether a rotation happened, for example because GitLab didn’t answer, it stops rotating that token and asks you to replace it. Retrying with a token GitLab may already have revoked could revoke the new one too. Replacing the token by hand always starts rotation fresh. Use a separate token for each connection. Peeps won’t connect a token that another connection already uses, because rotating it would leave the other connection holding the revoked one.
Need help connecting? Get in touch.