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

# Self-managed GitLab setup

> Connect CodeRabbit Agent for Slack to self-managed GitLab, configure repository access, and troubleshoot setup.

export const GitLabBadge = ({tip = "This feature is available on GitLab.", title = "GitLab", cta, href, disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="gitlab" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<GitLabBadge title="GitLab Self-Managed" tip="Set up CodeRabbit Agent for Slack with a self-managed GitLab instance." />

Connect your GitLab instance to CodeRabbit, link Slack, and configure the repositories Agent can use. This guide covers GitLab-specific setup; see the [Quickstart](/slack-agent/onboarding) for the general flow.

<Info>
  This guide is for organizations running their own GitLab server. To deploy CodeRabbit itself in your infrastructure, see [Self-hosted CodeRabbit](/self-hosted/overview).
</Info>

## Prerequisites

* A registered GitLab instance that CodeRabbit can reach over the network.
* A CodeRabbit organization admin to configure Agent. Billing-only admins cannot manage connections or scopes.
* Permission to install or authorize the app in your Slack workspace.
* A GitLab token valid for your instance with access to the intended groups and repositories. The setup form recommends a personal access token with the `api` scope.
* An active Agent trial, subscription, or add-on for the connected workspace. A Review or Advanced plan evaluation alone does not confirm Agent access. See [Agent billing](/slack-agent#billing).
* For SSO workspaces, confirm Agent access with [Support](/support) before setup. The repository-discovery rules below apply to workspaces with Agent access; SSO alone does not enable it.

## Register your GitLab instance

If this instance already uses CodeRabbit Review, reuse its registration. Otherwise, follow the [self-managed GitLab guide](/platforms/self-hosted-gitlab) to register the instance and configure the CodeRabbit user and OAuth application.

For IP-restricted instances, follow that guide's IP allowlist instructions. For private-network instances, contact [Support](/support) to arrange and verify Agent connectivity through the [CodeRabbit Reverse Tunnel](/self-hosted/coderabbit-reverse-tunnel).

## Setup steps

<Steps>
  <Step title="Select your CodeRabbit organization">
    Sign in to [CodeRabbit](https://app.coderabbit.ai) with the account for your self-managed instance, select the intended organization, and open **Slack**. The setup flow uses that organization's Git platform.
  </Step>

  <Step title="Connect Slack">
    Choose **Add to Slack** to install the app and grant the required [Slack permissions](/slack-agent/slack-permissions). If the workspace is already connected and you need to link your own account, choose **Connect Slack**. Existing installations resume at their next incomplete setup step.
  </Step>

  <Step title="Choose the GitLab token">
    In **GitLab API access**, select the token Agent should use:

    * **Inherit Review token** copies the CodeRabbit bot token stored for this GitLab instance into a separate Agent credential.
    * **Define new Agent token** saves a separate token for Agent. The token is not shown again after saving.

    If an Agent token is already configured, you can keep it or replace it. The temporary admin token used during instance registration is separate from the ongoing repository-access token.
  </Step>

  <Step title="Check repository access">
    Review the included repositories. GitLab lists are read-only, without per-repository checkboxes. Access depends on the token and whether your CodeRabbit workspace uses SSO, as explained below.
  </Step>

  <Step title="Save the Base Scope">
    Configure the default repositories, [connections](/connections), and spend controls. All available connections are selected initially; deselect any that should not be available across the workspace. Keep the intended GitLab connection selected. Agent cannot run until the Base Scope exists.
  </Step>

  <Step title="Verify access in Slack">
    In a channel where CodeRabbit is present, ask `@coderabbit` to read a specific file from an intended repository and summarize it without making changes. Check that the answer identifies the correct repository and file. This verifies read access, not permission to push changes or open merge requests.
  </Step>
</Steps>

## Understand repository access

A GitLab **instance** is the server, such as `https://gitlab.example.com`. A GitLab **group** can appear as an organization in CodeRabbit. A **scope** controls which context Agent can use in Slack; it does not grant new GitLab permissions.

Repository discovery differs by workspace type:

| CodeRabbit workspace | Repositories available to Agent                                                                                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Without SSO          | Repositories installed for CodeRabbit that the selected token can access. For a group organization, discovery includes that group and its subgroups.                                                                |
| With SSO             | Repositories in every visible, non-archived top-level group and its subgroups. A CodeRabbit Review installation is not required for each project. Personal namespace projects are excluded from this group catalog. |

For workspaces without SSO, the Scopes page can also show two diagnostic lists. **Visible to GitLab token** lists repositories the token can reach that are not installed for CodeRabbit. **Installed but not visible to GitLab token** lists installed repositories the token cannot reach. Both lists describe excluded repositories, not the included access set.

In an SSO workspace, each GitLab scope selects GitLab.com or one self-managed instance. Selecting a different GitLab token replaces the inherited access rather than combining repository sets. See [GitLab repository access](/slack-agent/connections-and-scopes#gitlab-repository-access).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Slack says the workspace subscription is inactive">
    Ask an admin to follow the billing link and check the Agent trial, subscription, or add-on for the connected workspace. Confirm which product the active trial covers: a Review or Advanced plan evaluation alone does not confirm Agent access. If Agent access is already active or the billing page shows a different account, contact [Support](/support) to verify the Slack installation's account linkage and Agent subscription before renewing or reinstalling.
  </Accordion>

  <Accordion title="The instance or expected organization is missing">
    Confirm that the instance is registered and the correct CodeRabbit organization is selected. Selecting a different GitLab organization during credential setup is available only in an SSO workspace. If the instance is missing or Agent access is unavailable, contact [Support](/support); do not register the same instance again.
  </Accordion>

  <Accordion title="The token is rejected or cannot be inherited">
    Check that the token belongs to the intended instance, has not expired or been revoked, and can access the intended groups and repositories. If no Review token is available to inherit, choose **Define new Agent token**. If the error persists, send the exact error text to [Support](/support).
  </Accordion>

  <Accordion title="Repositories are missing from the Base Scope">
    Check the selected organization, token permissions, and network connectivity. For workspaces without SSO, confirm that the intended repositories are installed for CodeRabbit. Use the diagnostic lists above to distinguish installation from token-access gaps.
  </Accordion>

  <Accordion title="Repositories work in Base Scope but not in a named scope">
    Check that the named scope includes the intended GitLab connection. Agent needs that connection for repository discovery and authentication. Assign it to the scope and retry. See [Connections and scopes](/slack-agent/connections-and-scopes) for scope management.
  </Accordion>

  <Accordion title="More than one GitLab credential matches">
    Leave only the intended GitLab connection selected in the scope, then save again.
  </Accordion>

  <Accordion title="Setup stays pending">
    Complete the GitLab token step and save the Base Scope. Return to the existing setup flow to resume; you do not need to start over. If registration is complete but an error reports a missing instance ID or host URL, contact [Support](/support).
  </Accordion>
</AccordionGroup>

When contacting Support, include the instance host URL, Slack workspace name and ID, affected scope, time of failure, and exact error text. For subscription errors, also include the failed Slack message link and the product and subscription ID shown as active. Do not include tokens, webhook secrets, private keys, or screenshots containing them.

## What's next

<CardGroup cols={1}>
  <Card title="Connections and scopes" href="/slack-agent/connections-and-scopes" icon="shield" horizontal>
    Configure access for specific channels or teams.
  </Card>

  <Card title="Working in Slack" href="/slack-agent/use-in-slack" icon="messages-square" horizontal>
    Start investigations and tasks from Slack.
  </Card>

  <Card title="Self-managed GitLab" href="/platforms/self-hosted-gitlab" icon="gitlab" horizontal>
    Review instance registration, OAuth setup, and repository installation.
  </Card>
</CardGroup>