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

# GitLab

> Connect GitLab.com or a self-managed GitLab with an access token so Compiler can read your repositories.

Compiler can read your code from GitLab, from GitHub, or from both. You connect GitLab with a GitLab access token. You don't need to create a GitLab application or set any environment variables.

This guide covers GitLab.com and self-managed GitLab.

## Prerequisites

* You're an owner or admin of your Compiler organization.
* A GitLab account that can create an access token for the groups or projects Compiler should read.

## Step 1: Create a bot user

Compiler reads every project the access token can see. Create the token on a dedicated bot user rather than your own account. That way you control exactly what Compiler can read.

1. Create a GitLab user for Compiler, for example `compiler-bot`.
2. Add it as a member of the groups or projects Compiler should read, with at least the **Reporter** role.

> [!TIP]
>
> To give Compiler more repositories later, add the bot user to more groups or projects. Nothing in Compiler needs to change.

## Step 2: Create an access token

Compiler accepts a personal, group or project access token. A personal token must be a legacy token.

> [!WARNING]
>
> Fine-grained tokens aren't supported. Compiler refuses them, saying to use a legacy token with the `read_api` and `read_repository` scopes.

> [tab] Personal access token
>
> 1. Sign in to GitLab as the bot user.
>
> 2. Open your user settings and go to **Access tokens**.
>
> 3. On GitLab.com, click **Generate token** and choose **Legacy token**. On a self-managed GitLab, click **Add new token**.
>
> 4. Give it a name such as `Compiler`, and set an expiry date.
>
> 5. Select the scopes from the table below.
>
> 6. Click **Create token** and copy it.
>
> > [!TIP]
> >
> > In Compiler's token form, the **user settings** link opens this form already filled in, with the name `Compiler` and the `read_api`, `read_repository` and `self_rotate` scopes. Sign in as the bot user first.

> [tab] Group or project access token
>
> 1. In GitLab, open the group or project, then **Settings** > **Access tokens**.
> 2. Click **Add new token**, give it a name such as `Compiler`, and set an expiry date.
> 3. Set the role to **Reporter** or higher.
> 4. Select the scopes from the table below.
> 5. Click **Create token** and copy it.
>
> A group or project access token only reads that group or project.

The token needs these scopes:

| Scope | Required | Purpose |
| - | - | - |
| `read_api` | Yes | List projects and read repository details |
| `read_repository` | Yes | Clone and fetch repositories |
| `self_rotate` | No | Let Compiler renew the token before it expires |

A personal access token with the `api` scope also works instead of `read_api`, but it grants write access that Compiler doesn't use.

> [!WARNING]
>
> Copy the token before you leave the page. GitLab only shows it once.

## Step 3: Connect GitLab

> [tab] During setup
>
> 1. After you create the owner account, setup asks for a GitHub App. Below the form, next to **Code on GitLab?**, click **Connect GitLab instead**.
> 2. Click **Connect GitLab**.
> 3. Paste the token into **API access token**.
> 4. For self-managed GitLab, enter its address in **Custom GitLab URL (optional, self-hosted only)**, for example `https://gitlab.your-company.com`. Leave it blank for GitLab.com.
> 5. Click **Connect**.
>
> Setup then moves on to choosing your AI provider and creating your first project, where you pick repositories from GitLab.

> [tab] From settings
>
> 1. In Compiler, open **Settings** > **GitLab**.
> 2. Under **Connections**, click **Connect GitLab**.
> 3. Paste the token into **API access token**.
> 4. For self-managed GitLab, enter its address in **Custom GitLab URL (optional, self-hosted only)**, for example `https://gitlab.your-company.com`. Leave it blank for GitLab.com.
> 5. Click **Connect**.

Compiler checks the token before it saves it. The token is stored encrypted.

> [!NOTE]
>
> For self-managed GitLab, your instance needs to reach that address. If your network restricts egress, allow it alongside the other [outbound hosts](https://docs.usecompiler.com/deployment/other-platforms.md#step-7-allow-outbound-access).

## Step 4: Add repositories to a project

If you connected GitLab during setup, your first project already has the repositories you picked. To add more, or to add them to another project, use settings.

Once connected, **Settings** > **GitLab** lists the repositories the token can read under **Repositories**.

To add them to a project:

1. Open **Settings**, choose the project, and go to **Repositories**.
2. Under **Add repository**, pick repositories from GitLab. Projects in nested groups are included.

If you've also connected a [GitHub App](https://docs.usecompiler.com/configuration/github-app.md), the list shows repositories from both, each with its provider's icon, and a project can mix them.

You can also add a public repository by pasting its URL. Compiler adds it from whichever provider it belongs to: github.com, gitlab.com or your connected self-managed GitLab.

Compiler clones the repositories in the background. You can start asking questions while they sync.

If no repositories appear, add the bot user to a GitLab group or project with at least the **Reporter** role.

## Token expiry

GitLab access tokens expire. **Settings** > **GitLab** shows the expiry date next to the connection.

* If the token has the `self_rotate` scope, Compiler renews it automatically before it expires.
* Otherwise, create a new token and replace it before the old one expires. Open the **⋯** menu next to the connection and choose **Replace access token**.

If GitLab stops accepting the token, because it was revoked or it expired, the page says the connection needs reconnecting. Replace the access token, or click **Reconnect GitLab**, and paste a new one.

## Disconnect

Open the **⋯** menu next to the connection and choose **Disconnect**, then **Disconnect now**.

Repositories already in projects stay, with the code they last synced.

To connect a different GitLab, for example to move from GitLab.com to a self-managed GitLab, first remove the repositories from the current GitLab from every project.

## Scopes summary

| Scope | Required | Purpose |
| - | - | - |
| `read_api` | Yes | List projects, read details |
| `read_repository` | Yes | Clone and fetch repositories |
| `self_rotate` | No | Renew the token automatically |
| All others | No | Not used |


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