# Connect GitLab.

Connect selected projects from GitLab.com or a self-managed GitLab server. Perfloop reads their code and opens merge requests for proven changes. You review and merge them.

If Setup has no GitLab tab, contact [hello@perfloop.ai](mailto:hello@perfloop.ai?subject=GitLab%20connection).

## Access you need

- dedicated bot · api scope Use a group access token, a project access token, or a personal access token of a dedicated service account. The account must be an active GitLab bot. Personal tokens of people are refused. Your GitLab plan must support the token kind you choose; a paid plan is not required for every token kind.
- Developer · selected projects Give the bot at least the Developer role on each project you select. The api scope can grant more access than Perfloop uses. Limit the bot to the projects it needs. Perfloop works only on the selection you save, even if the token can reach other projects.

Perfloop can push a branch, open and update its merge requests, read their checks and discussion, and answer feedback. It cannot approve or merge a merge request, deploy, or change project settings. Keep your default branch protected and your review and CI requirements in place.

## Setup

### 1 · prepare the connection

Create the bot token in GitLab with the api scope and the project access above. Keep it in a secret store. Enter it only in Perfloop's Setup form, never in a chat or an MCP call.

For GitLab.com, use `https://gitlab.com` and leave Relay name and Root CA empty. A public self-managed server can also connect directly. For a private server, configure a [code-host relay upstream](https://perfloop.ai/docs/connect/relay#code-hosts) first. Its URL must be the same HTTPS origin you enter in Setup, including a non-default port.

If your server uses a private certificate authority, have its public root CA certificates in PEM format ready. Never paste a private key. Perfloop checks the server's hostname and certificate; there is no option to turn TLS verification off.

### 2 · list and choose projects

As a workspace Admin, open **Setup → Connections → Code host → GitLab** and select **Connect GitLab**. Enter **Instance URL** and **Access token**. For a private server, enter the upstream's name in **Relay name**, without `relay://`. Paste the public CA certificates in **Root CA** if needed.

Select **List projects**, then tick the projects Perfloop may use. Listing saves no connection. Select **Connect** to save the selection. Perfloop checks access to every chosen project. A connected row and the selected projects appear in Setup. Perfloop never shows the token again.

### 3 · choose the work

The selected projects use the same system model and Case workflow as other code hosts. Automatic work is controlled separately in **Setup → Automatic work**. With **Pull requests** set to **Ask**, a proven change waits for your decision in Inbox before Perfloop opens its merge request. See [Autonomy and limits](https://perfloop.ai/docs/work/autonomy).

## Data Perfloop reads and keeps

Perfloop reads selected source code, project metadata, and merge-request changes, checks and discussion. It keeps the system model, Cases and their proof, and the connection details needed to use those projects. The token is stored encrypted and is not given to coding agents or sandboxes.

Selected code can enter model context through OpenAI under zero-data-retention terms. Perfloop does not use your code to train models. See [Security](https://perfloop.ai/security) for data handling.

## Change the token or project selection

Before the token expires, create its replacement in GitLab. Select **Reconnect** on the saved connection. Enter the fresh token and select **List projects**. Saved projects the token can reach start ticked. The checked list replaces the previous selection when you select **Reconnect**. Unticked projects lose selection. Revoke a replaced token in GitLab too.

A reconnect keeps its instance URL. To use another server, select **Connect another GitLab instance**.

## Remove access

Select **Disconnect** and confirm. Perfloop stops reading and writing through that connection. Open merge requests stay in GitLab. Revoke the bot token in GitLab to remove its provider access too.

Disconnecting does not delete records or proof already stored by Perfloop. Deleting the workspace removes its stored data. A disconnected connection needs a fresh token and project selection before use again.

Security questions: [security@perfloop.ai](mailto:security@perfloop.ai?subject=GitLab%20connection%20review)