> ## 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](/platforms/overview).

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

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

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

<Info>
  **Using self-hosted GitLab?** See our [Self-managed
  GitLab](/platforms/self-hosted-gitlab) integration guide for on-premises
  installations.
</Info>

## 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.

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

<CardGroup cols={2}>
  <Card title="Personal Access Token" icon="user" href="#personal-access-token">
    Create a dedicated service account for CodeRabbit with a personal access
    token
  </Card>

  <Card title="Group Access Token" icon="users" href="#group-access-token">
    Use GitLab Premium/Ultimate's group tokens with automatic bot user creation
  </Card>
</CardGroup>

### Personal Access Token

We recommend creating a new user as a service account, associating this user to the group you'd like to install CodeRabbit on, 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.

<img src="https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab_user_choice.png?fit=max&auto=format&n=69LGK0BhaHIxrC15&q=85&s=281f3f6e272e78484971861e8726e555" alt="GitLab user modal showing options to add a personal access token for CodeRabbit integration" width="1680" height="1215" data-path="images/platforms/img/integrations/gitlab_user_choice.png" />

<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.
</Note>

<img src="https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab_organization_user.png?fit=max&auto=format&n=69LGK0BhaHIxrC15&q=85&s=c528ffec43b52bbb3ad23718e6edefe8" alt="GitLab organization user selection modal for configuring CodeRabbit access" width="1686" height="1227" data-path="images/platforms/img/integrations/gitlab_organization_user.png" />

#### 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.
</Tip>

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 group or projects where you want to install 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.
</Warning>

<Info>
  **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.
</Info>

**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

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

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

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

  <Step title="Select required scopes">
    Ensure the following scopes are selected: - `api` - Full API access -
    `read_api` - Read-only API access - `read_user` - Read user information
  </Step>

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

<img src="https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/admin-access-token.png?fit=max&auto=format&n=69LGK0BhaHIxrC15&q=85&s=72725c949136b3ee470aefcdb11dac62" alt="GitLab personal access token creation page showing required scopes and settings for CodeRabbit integration" width="1816" height="941" data-path="images/platforms/img/integrations/admin-access-token.png" />

***

### Group Access Token

Creating a Group Access Token in GitLab automatically generates a bot user. Ensure that the token is configured with Developer access. Once set up, you only need to provide this token for integration. Note that a Group Access Token is limited to the scope of the group where it was created. To configure additional groups, you will need to generate a separate Group Access Token for each group.

<Note>
  By default, GitLab restricts this option to users on the Premium or Ultimate
  tiers.
</Note>

#### Generating a Group Access Token

<Steps>
  <Step title="Navigate to your group">
    Navigate to the group you wish to install CodeRabbit on.
  </Step>

  <Step title="Access token settings">
    1. Select **Settings** from the left sidebar 2. Select **Access Tokens**
       within the Settings heading
  </Step>

  <Step title="Create the token">
    1. Create a Group Access Token 2. Ensure the `api` scope is selected 3.
       Ensure **Developer Access** is provided
  </Step>
</Steps>

<Check>
  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 bot's user ID through the CodeRabbit UI if connected, or by visiting the bot user's profile from your Group Members page in GitLab.
</Check>

### Configuring Access Tokens in CodeRabbit

GitLab onboarding requirement: The user completing the CodeRabbit onboarding flow must be a GitLab group owner. By default, if no access token is provided, CodeRabbit will prompt you to provide one during the installation process. However, if you wish to provide the token beforehand, you can do so by navigating to the **Organization Settings** tab, and selecting the **GitLab User** tab on the sidebar. Once entering the token, the token will be validated and saved 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

<Steps>
  <Step title="Access repository settings">
    Go to the [Repositories
    page](https://app.coderabbit.ai/settings/repositories) in the CodeRabbit
    app.
  </Step>

  <Step title="Select repositories">
    Select the checkbox next to the repositories where you want to install
    CodeRabbit.

    <Tip>
      To install CodeRabbit on all repositories at once, select the checkbox at
      the top.
    </Tip>
  </Step>

  <Step title="Install CodeRabbit">
    Select **Install Repositories** to complete the installation.
  </Step>
</Steps>

<img src="https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab-repo-install.png?fit=max&auto=format&n=69LGK0BhaHIxrC15&q=85&s=f1ce504cee948da2087bc0b996dcdb6e" alt="CodeRabbit repository installation modal showing GitLab repositories available for integration" width="1874" height="1468" data-path="images/platforms/img/integrations/gitlab-repo-install.png" />

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

<img src="https://mintcdn.com/coderabbit/69LGK0BhaHIxrC15/images/platforms/img/integrations/gitlab-webhook.png?fit=max&auto=format&n=69LGK0BhaHIxrC15&q=85&s=b471c4147b9f77e08fbf1c5c1ffbe17c" alt="GitLab webhook configuration showing CodeRabbit's webhook URL installed in project settings" width="3024" height="1514" data-path="images/platforms/img/integrations/gitlab-webhook.png" />

## 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 for both GitLab.com and self-managed GitLab.

<Steps>
  <Step title="Open Webhook Secret settings">
    In the CodeRabbit app, open **Account** and select **Webhook Secret** from
    the sidebar.
  </Step>

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

  <Step title="Save or change the webhook secret">
    Enter the secret that GitLab should send with webhook deliveries and save
    it in CodeRabbit.
  </Step>

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

<Info>
  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.
</Info>

## Troubleshooting

<Note>
  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.
</Note>