> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peepsai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect GitLab

> Connect a GitLab group to your Peeps organization so a project's tests can live in a GitLab repository and run in GitLab CI/CD. Works with gitlab.com and self-managed GitLab.

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.

<Tabs>
  <Tab title="Group access token">
    <Steps>
      <Step title="Open the group's access tokens">
        In GitLab, open the group that holds your test projects, then **Settings** > **Access tokens**. Click **Add new token**.
      </Step>

      <Step title="Choose the role and scope">
        Set **Role** to **Maintainer** and select the **api** scope.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal access token">
    <Steps>
      <Step title="Use a Maintainer of the group">
        Sign in as a user with the **Maintainer** role on the group. Peeps comments, commits and opens merge requests as this user, so a dedicated user for Peeps works best.
      </Step>

      <Step title="Open your access tokens">
        Open **User settings** > **Access tokens** and click **Add new token**. Select the **api** scope.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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](#token-rotation)).

## Connect the group

<Steps>
  <Step title="Open GitLab settings in Peeps">
    In Peeps, open **Settings** and select **GitLab** under **Organization**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](mailto:support@peepsai.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.