Skip to main content
Connect your GitLab instance to CodeRabbit, link Slack, and configure the repositories Agent can use. This guide covers GitLab-specific setup; see the Quickstart for the general flow.
This guide is for organizations running their own GitLab server. To deploy CodeRabbit itself in your infrastructure, see Self-hosted CodeRabbit.

​
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.
  • For SSO workspaces, confirm Agent access with 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 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 to arrange and verify Agent connectivity through the CodeRabbit Reverse Tunnel.

​
Setup steps

1

Select your CodeRabbit organization

Sign in to CodeRabbit with the account for your self-managed instance, select the intended organization, and open Slack. The setup flow uses that organization’s Git platform.
2

Connect Slack

Choose Add to Slack to install the app and grant the required 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.
3

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

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

Save the Base Scope

Configure the default repositories, 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.
6

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.

​
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: 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.

​
Troubleshooting

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 to verify the Slack installation’s account linkage and Agent subscription before renewing or reinstalling.
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; do not register the same instance again.
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.
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.
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 for scope management.
Leave only the intended GitLab connection selected in the scope, then save again.
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.
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

Connections and scopes

Configure access for specific channels or teams.

Working in Slack

Start investigations and tasks from Slack.

Self-managed GitLab

Review instance registration, OAuth setup, and repository installation.