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

# GitLab

> Learn how to integrate CodeRabbit with GitLab.com repositories using personal or group access tokens for automated AI-powered code reviews and collaboration.

For an overview of how CodeRabbit integrates with Git platforms, see [Platform Integration Overview](https://docs.coderabbit.ai/platforms/overview.md).

For a hands-on tutorial with CodeRabbit performing code reviews on a live repository, see [Quickstart](https://docs.coderabbit.ai/getting-started/quickstart.md).

CodeRabbit enhances your GitLab.com development workflow by providing:

* **Automated code reviews** for newly created merge requests
* **AI-powered suggestions** displayed directly on merge requests
* **Interactive assistance** through the CodeRabbit bot for real-time feedback
* **Seamless integration** with your existing GitLab workflow

> [!NOTE]
>
> To interact with CodeRabbit in merge request comments, use `@coderabbitai` — or the username of the service account you configure below, if it differs.

> [!NOTE]
>
> **Using self-hosted GitLab?** See our [Self-managed
> GitLab](https://docs.coderabbit.ai/platforms/self-hosted-gitlab.md) integration guide for on-premises
> installations.

## GitLab Access Tokens

To enable CodeRabbit to interact with your GitLab repositories, you need to provide an access token that grants the necessary permissions for the Merge Requests and Discussions APIs.

### Group scope and permissions

For group-based setup, the person installing CodeRabbit and the identity behind the review token have separate permission requirements:

| Identity | Required GitLab access |
| - | - |
| Person installing on individual projects | Maintainer or Owner on each project |
| Person using **Install Group** | Owner of the top-level group |
| Service account or group token bot that posts reviews | Developer or higher in the top-level group selected in CodeRabbit, with the token scopes described below |

CodeRabbit validates the review token against the selected top-level group before you choose repositories or subgroups. Access only to a descendant subgroup or individual projects does not satisfy this organization token check. This requirement also applies when you replace the organization's token under **Account** → **GitLab User**.

> [!NOTE]
>
> A token's role and its group scope are separate. Owner access in a subgroup does not grant access to its parent group. See [token permission troubleshooting](#token-requires-developer-access) if validation fails.

Choose the token type that best fits your organization's needs:

> [card] [Personal Access Token](#personal-access-token)
>
> Create a dedicated service account for CodeRabbit with a personal access
> token

> [card] [Group Access Token](#group-access-token)
>
> Use GitLab Premium/Ultimate's group tokens with automatic bot user creation

### Personal Access Token

We recommend creating a new user as a service account, adding this user to the top-level GitLab group selected in CodeRabbit, and providing CodeRabbit with the personal access token to allow access. During the installation process, CodeRabbit will automatically configure the required webhook for seamless integration.

![GitLab user modal showing options to add a personal access token for CodeRabbit integration](https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab_user_choice.png?fit=max\&auto=format\&n=69LGK0BhaHIxrC15\&q=85\&s=281f3f6e272e78484971861e8726e555)

> [!NOTE]
>
> If you wish to change the review user, you must provide the access token for
> the new user who will post reviews and comments. However, this requires
> manually removing the previous user from the projects and associated webhooks.
> Once this is done, you will need to reinstall the CodeRabbit app for each
> project.

![GitLab organization user selection modal for configuring CodeRabbit access](https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab_organization_user.png?fit=max\&auto=format\&n=69LGK0BhaHIxrC15\&q=85\&s=c528ffec43b52bbb3ad23718e6edefe8)

#### Best Practices for Service Account Setup

> [!TIP]
>
> **Create a dedicated user for CodeRabbit** - This ensures the user is
> exclusively for CodeRabbit, allowing better access control and easier
> management.

Follow these recommendations when setting up your CodeRabbit service account:

* **Username**: Use "CodeRabbit" as the username for easy recognition
* **Email**: Use a dedicated email address for easy identification and management
* **Profile picture**: Use the CodeRabbit logo for easy recognition. [Download our logo here](https://www.coderabbit.ai/brand)
* **Permissions**: Ensure the dedicated user has at least **Developer** access to the top-level GitLab group selected in CodeRabbit

#### Important Considerations

> [!WARNING]
>
> **Token Expiration**: Personal access tokens have expiration dates. Ensure the
> expiration date covers the duration of your intended use of CodeRabbit to
> avoid service interruption.

> [!NOTE]
>
> **Review Attribution**: Code reviews will be attributed to the owner of the
> personal access token, so they'll appear to come from your service account
> user.

**Updating Expired Tokens**: If your personal access token expires, you can add a new one via the CodeRabbit UI:

1. Navigate to the **GitLab User** page in the sidebar
2. Enter the new access token and click the **Update** button

#### Generating a Personal Access Token

**1. Log in to your CodeRabbit service account**

Log in using the user designated for CodeRabbit reviews. This user serves as
a service account for managing reviews and related activities.

**2. Navigate to access tokens**

1. Select your avatar on the left sidebar 2. Choose **Edit Profile** 3.
   Select **Access Tokens** from the left sidebar 4. Click [Add New
   Token](https://gitlab.com/-/user_settings/personal_access_tokens)

**3. Configure token settings**

1. Enter a descriptive name for the token (e.g., "CodeRabbit Integration")
2. Set an expiry date for the token

> [!NOTE]
>
> If no expiry date is entered, it defaults to 365 days from the current
> date.

**4. Select required scopes**

Ensure the following scopes are selected: - `api` - Full API access -
`read_api` - Read-only API access - `read_user` - Read user information

**5. Create and save the token**

1. Click **Create Personal Access Token** 2. **Important:** Copy and
   securely store the token immediately as it will only be displayed once

![GitLab personal access token creation page showing required scopes and settings for CodeRabbit integration](https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/admin-access-token.png?fit=max\&auto=format\&n=69LGK0BhaHIxrC15\&q=85\&s=72725c949136b3ee470aefcdb11dac62)

***

### Fine-Grained Personal Access Token

> [!NOTE]
>
> Fine-grained personal access tokens are generally available in **GitLab
> 19.2** and later, on all tiers. On earlier versions, use a classic personal
> access token or a group access token.

A fine-grained personal access token grants only the permissions you select, instead of the blanket `api` scope. If your security review cannot approve "complete read and write access to the API", this is the option to use.

CodeRabbit accepts a fine-grained token anywhere a personal access token is accepted — paste it into the same field. Nothing else changes.

#### Generating a fine-grained token

**1. Log in to your CodeRabbit service account**

Create the token on the dedicated service account, not on a human user's account — GitLab does not let a user review their own merge requests.

**2. Add a fine-grained token**

Select your avatar → **Edit profile** → **Access** → **Personal access tokens**, then from the **Generate token** dropdown select **Fine-grained token**.

**3. Set name, expiry, and resources**

Enter a descriptive name and expiry, then select the group or projects CodeRabbit reviews — plus any **linked repositories** used for cross-repo context — as the token's resources. Also add the service-account user as a resource: the **User access** permissions below (for example `GET /user`) sit on GitLab's User boundary, so a group or project selection alone does not grant them.

Selecting a **group** here is only about *scope* (covering every project under it in one token) — it does **not** require the group-level permissions below. Those are needed only for a group-level install (see **Group access**).

**4. Select permissions**

Grant the permissions listed under **Required permissions** below. Do **not** select the classic `api`, `read_api`, or `read_user` scopes — those apply only to classic tokens; fine-grained tokens use the resource permissions below instead.

**5. Create and save the token**

Select **Generate token**, then copy and store it immediately — it is shown only once.

#### Required permissions

Grant these to the group or projects CodeRabbit reviews. This is the complete set CodeRabbit may call across the REST features below. **For a review-only service account, the Project access and User access permissions are sufficient — the Group access permissions are needed only when CodeRabbit is installed on a group rather than on individual projects.** A narrower set works if you do not use every feature — committing fixes needs **Branch: Create**, **Branch: Delete** and **Commit: Create**; CI failure analysis needs **Pipeline: Read** and **Job: Read**. Reviewing **linked repositories** for cross-repo context additionally needs **Code: Read** and **Code: Download** (clone access) on GitLab's GraphQL `Repository` type, and each linked repository must itself be selected as a token resource — its clone uses the same token and otherwise falls outside the token's resource boundary. The REST tables below do not cover these.

> [!WARNING]
>
> GitLab does not let a user review their own merge requests. Create the token
> on a dedicated service account, not on a human user's account.

##### Project access

| Permission | Example endpoints |
| - | - |
| **Branch: Create** | `POST /projects/:id/repository/branches` |
| **Branch: Delete** | `DELETE /projects/:id/repository/branches/:branch` |
| **Branch: Read** | `GET /projects/:id/repository/branches`, `GET /projects/:id/repository/branches/:branch` |
| **Commit Status: Create** | `POST /projects/:id/statuses/:sha` |
| **Commit: Create** | `POST /projects/:id/repository/commits` |
| **Commit: Read** | `GET /projects/:id/repository/commits`, `GET /projects/:id/repository/commits/:sha/statuses` |
| **Global Search: Use** | `GET /projects/:id/(-/)search` |
| **Job: Read** | `GET /projects/:id/jobs/:job_id/trace` |
| **Label: Read** | `GET /projects/:id/labels` |
| **Member: Read** | `GET /projects/:id/members`, `GET /projects/:id/members/all` |
| **Merge Request: Approve** | `POST /projects/:id/merge_requests/:merge_request_iid/approve`, `POST /projects/:id/merge_requests/:merge_request_iid/unapprove` |
| **Merge Request: Create** | `POST /projects/:id/merge_requests`, `POST /projects/:id/merge_requests/:noteable_id/discussions` |
| **Merge Request: Merge** | `PUT /projects/:id/merge_requests/:merge_request_iid/merge` |
| **Merge Request: Read** | `GET /projects/:id/merge_requests/:merge_request_iid`, `GET /projects/:id/merge_requests/:merge_request_iid/diffs` |
| **Merge Request: Update** | `PUT /projects/:id/merge_requests/:merge_request_iid`, `PUT /projects/:id/merge_requests/:merge_request_iid/rebase` |
| **Pipeline: Read** | `GET /projects/:id/pipelines`, `GET /projects/:id/pipelines/:pipeline_id` |
| **Project: Read** | `GET /projects/:id` |
| **Repository: Read** | `GET /projects/:id/repository/compare`, `GET /projects/:id/repository/files/:file_path` |
| **Vulnerability: Read** | `GET /projects/:id/vulnerabilities` |
| **Work Item: Create** | `POST /projects/:id/merge_requests/:noteable_id/notes`, `POST /projects/:id/merge_requests/:merge_request_iid/notes/:note_id/award_emoji` |
| **Work Item: Delete** | `DELETE /projects/:id/merge_requests/:noteable_id/notes/:note_id`, `DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id/award_emoji/:award_id` |
| **Work Item: Read** | `GET /projects/:id/merge_requests/:noteable_id/notes`, `GET /projects/:id/issues/:issue_iid` |
| **Work Item: Update** | `PUT /projects/:id/merge_requests/:noteable_id/notes/:note_id`, `PUT /projects/:id/issues/:issue_iid` |

##### Group access

Required when CodeRabbit is installed on a group rather than on individual projects.

| Permission | Example endpoints |
| - | - |
| **Global Search: Use** | `GET /groups/:id/(-/)search` |
| **Group: Read** | `GET /groups/:id` |
| **Member: Read** | `GET /groups/:id/members`, `GET /groups/:id/members/all` |
| **Merge Request: Read** | `GET /groups/:id/merge_requests` |
| **Project: Read** | `GET /groups/:id/projects` |

##### User access

Identifies the service account itself and resolves the namespaces it can reach.

| Permission | Example endpoints |
| - | - |
| **Group: Read** | `GET /groups` |
| **Namespace: Read** | `GET /namespaces`, `GET /namespaces/:id` |
| **Project: Read** | `GET /projects`, `GET /users/:user_id/projects` |
| **User: Read** | `GET /user`, `GET /users/:id` |
| **Work Item: Read** | `GET /issues` |

#### If a permission is missing

GitLab rejects the call and names what it needed:

```text theme={null}
Access denied: This operation requires a fine-grained personal access token
with the following project permissions: [Merge Request: Update].
```

Add the named permission to the token and retry.

***

### Group Access Token

Creating a Group Access Token in GitLab automatically generates a bot user. Create the token in the top-level group selected in CodeRabbit, with Developer access or higher and the `api` scope. The bot inherits access to that group's subgroups and projects, but a token created in a subgroup does not grant access to its parent. To configure another top-level group, create a separate Group Access Token for that group.

> [!NOTE]
>
> By default, GitLab restricts this option to users on the Premium or Ultimate
> tiers.

#### Generating a Group Access Token

**1. Navigate to your group**

Navigate to the top-level GitLab group selected in CodeRabbit. You must have the Owner role in that group to create a Group Access Token; GitLab instance administrator access is not required.

**2. Access token settings**

1. Select **Settings** from the left sidebar 2. Select **Access Tokens**
   within the Settings heading

**3. Create the token**

1. Select the `api` scope.
2. Select **Developer** or higher for the token's role. The token itself does not need the Owner role.
3. Create the Group Access Token.

> [!TIP]
>
> Group Access Tokens create bot users with generic GitLab-generated usernames (like `group_63_bot_5753...`). If you prefer a more descriptive username for your CodeRabbit bot, you can customize it using the [GitLab API](https://docs.gitlab.com/api/users/#modify-a-user).
>
> You can find the user ID of the bot through the CodeRabbit UI if connected, or by visiting the bot user's profile from your Group Members page in GitLab.

### Configuring Access Tokens in CodeRabbit

GitLab project Owners and Maintainers can install CodeRabbit on individual projects from the **Repositories** page without requiring top-level GitLab group Owner access, including projects inside subgroups. The **Install Group** action is restricted to GitLab group Owners.

These installer permissions are separate from the [review token's group access requirements](#group-scope-and-permissions).

By default, if no access token is provided, CodeRabbit prompts you to provide one during installation. To provide the token beforehand, open **Account** in the left sidebar, then under **Provider settings**, click **GitLab User**. Once you enter the token, CodeRabbit validates it and saves it for future use.

You can confirm the correct user is being selected by verifying the user ID shown on the UI with the user ID of the service account user you created.

***

## Repository Installation

You can install CodeRabbit on individual GitLab projects or across a full GitLab group, depending on your GitLab role. Projects are selectable based on your permissions:

* **Project installation**: GitLab project Owners and Maintainers can install CodeRabbit on the selected projects without top-level group Owner access.
* **Group installation**: Installing CodeRabbit for an entire GitLab group requires GitLab group Owner access, and the installation covers repositories in that group and its subgroups, including [repositories added later](#automatic-installation-for-new-group-repositories). Group-wide install and uninstall actions are managed from the top-level group; when browsing a subgroup, the group-wide action is not shown, but you can still select individual repositories or, if you manage the top-level group, choose **View top-level group** to manage the group installation.

Projects where your GitLab user has Owner or Maintainer access are selectable. Projects where you do not have enough permission remain visible but cannot be selected; CodeRabbit shows a reason message explaining why the project is unavailable.

Selecting individual repositories controls where CodeRabbit is installed. It does not restrict which repositories the review token can access in GitLab. If you need a token restricted to specific projects or a subgroup, [contact support](https://docs.coderabbit.ai/support) to discuss that requirement before granting broader group access. The organization token setup described on this page requires access to the selected top-level group.

**1. Access repository settings**

Go to the [Repositories
page](https://app.coderabbit.ai/settings/repositories) in the CodeRabbit
app.

**2. Select repositories**

Select the checkbox next to the projects where you want to install CodeRabbit.

> [!TIP]
>
> To install CodeRabbit on every project in a group, use the group-level installation option. This action requires GitLab group Owner access.

**3. Install CodeRabbit**

Select **Install Repositories** to complete the installation.

![CodeRabbit Repositories page showing selectable GitLab projects and unavailable projects based on user permissions](https://mintcdn.com/coderabbit/U3vyChU571k_ZaDL/assets/images/gitlab-project-installation-permissions.png?fit=max\&auto=format\&n=U3vyChU571k_ZaDL\&q=85\&s=006e622f3631688284606540fde8f57b)

Selectable and unavailable GitLab projects on the CodeRabbit Repositories page

The webhook `https://coderabbit.ai/gitlabHandler` will now be installed for the projects selected.

![GitLab webhook configuration showing CodeRabbit's webhook URL installed in project settings](https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab-webhook.png?fit=max\&auto=format\&n=69LGK0BhaHIxrC15\&q=85\&s=b471c4147b9f77e08fbf1c5c1ffbe17c)

### Automatic installation for new group repositories

After a GitLab group Owner completes the **Install Group** action, CodeRabbit also covers repositories that are later created in or added to the installed group and its subgroups. You do not need to select and install each new repository individually.

This behavior relies on the group-level webhook and token installation. Use a Group Access Token where applicable, and complete the group installation as a GitLab group Owner.

> [!NOTE]
>
> On GitLab.com, Group Access Tokens are available on the Premium and Ultimate tiers.

Activation is event-driven rather than immediate when the repository is created or added. CodeRabbit marks the repository as installed when its first merge request or pull request is opened and then begins the review.

After activation, use [Repository settings](https://docs.coderabbit.ai/configuration/web-app.md) to verify access or manage the repository in CodeRabbit.

## Manual webhook installation

If you install repositories from the **Repositories** page, CodeRabbit configures the webhook automatically. Use this flow only when you need to install the webhook manually or rotate the shared webhook secret.

The **Webhook Secret** page is available in CodeRabbit for supported Git providers, including GitLab.com and self-managed GitLab. For an instance-wide shared secret on self-managed GitLab, use [Workspace Git credentials](https://docs.coderabbit.ai/platforms/self-hosted-gitlab.md#rotate-the-instance-wide-shared-secret).

**1. Open Webhook Secret settings**

In the CodeRabbit app, open **Account** and select **Webhook Secret** from
the sidebar.

**2. Copy the webhook URL**

Use the **Webhook URL** field on that page to copy the exact endpoint that
your GitLab project or group should call.

**3. Save or change the webhook secret**

Enter the secret that GitLab should send with webhook deliveries and save
it in CodeRabbit.

**4. Configure the GitLab webhook**

When creating or editing the webhook in GitLab, use the copied webhook URL
and enable these settings:

* **Merge request events**
* **Comments**
* **Issues events**
* **SSL verification** enabled

> [!NOTE]
>
> If you change an existing webhook secret, CodeRabbit attempts to update existing CodeRabbit-managed GitLab project and group webhooks automatically. If a webhook was created manually, or if an automatic refresh fails, update the secret directly in GitLab.

## Troubleshooting

### Token requires Developer access

The error "The token requires Developer access to the selected GitLab group" refers to the service account or bot identity behind the token. Check its access to the top-level group selected in CodeRabbit, even if the person installing CodeRabbit is a group Owner.

For example, if you select `example-org` in CodeRabbit and create a Group Access Token in `example-org/backend`, the token can have Owner access to `backend` and still fail validation for `example-org`. Increasing its role within `backend` does not grant access to the parent group.

If access across the parent group is acceptable, use a Group Access Token created in `example-org` with Developer access or higher and `api`, or a personal access token for a service account with the required access to `example-org` and [personal token scopes](#generating-a-personal-access-token). If you need subgroup-only or project-only access, contact support before expanding permissions; choosing a subgroup later in repository selection does not change the group used to validate the token.

If the token identity already has Developer access or higher in the selected top-level group, confirm the token is active and has the required scopes, then [contact support](https://docs.coderabbit.ai/support) with the selected group URL and error message. Do not share the token value.

### Webhook issues

If you are experiencing issues with the webhook, such as CodeRabbit not being able to access the repository, or not reviewing merge requests, you can manually delete the webhook from the repository.

Then refresh the repository page in the CodeRabbit app and reinstall the webhook.

If you cannot install the webhook, please check that your GitLab user has the necessary permissions to install the webhook and the PAT is not expired.


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