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

# GitLab

> Connect GitLab repositories for automated merge request reviews and security scanning.

# GitLab Integration

Corridor integrates with GitLab to import your repositories, scan code for security vulnerabilities, and generate guardrails tailored to each project. When merge requests are opened or updated, Corridor automatically reviews the changes and posts findings directly on the MR.

<Warning>
  The GitLab integration is currently in **beta**. To enable it for your organization, contact the Corridor team at [support@corridor.dev](mailto:support@corridor.dev).
</Warning>

## What you get

* **Automated MR reviews**: Every merge request analyzed for security vulnerabilities
* **Inline comments**: Findings posted directly on the affected code lines
* **Finding tracking**: Issues persist and track through remediation
* **Guardrail generation**: Security guardrails tailored to your project's stack

## Prerequisites

* A Corridor account with admin access to your team
* A GitLab account with access to the group containing your repositories

## Connecting GitLab.com

<Steps>
  <Step title="Start GitLab connection">
    In the Corridor dashboard, go to **Teams** and click **Connect GitLab**.
  </Step>

  <Step title="Authorize Corridor">
    You'll be redirected to GitLab to authorize Corridor. Review the permissions and click **Authorize**.
  </Step>

  <Step title="Select a GitLab group">
    After authorization, select the GitLab group containing the repositories you want to monitor.

    <Note>
      Only one group can be connected per team. If you need to change groups later, you'll need to disconnect and reconnect.
    </Note>
  </Step>
</Steps>

## Connecting a Self-Hosted GitLab Instance

Self-hosted GitLab instances require you to create an OAuth application on your GitLab instance so that Corridor can authenticate with it.

<Warning>
  Before setting up the integration, contact the Corridor team at [support@corridor.dev](mailto:support@corridor.dev) to have your GitLab instance domain whitelisted. The connection will not work until this step is complete.
</Warning>

<Steps>
  <Step title="Contact Corridor to whitelist your domain">
    Email [support@corridor.dev](mailto:support@corridor.dev) with your self-hosted GitLab instance URL (e.g., `https://gitlab.yourcompany.com`). The Corridor team will whitelist your domain so the integration can communicate with your instance.
  </Step>

  <Step title="Create an OAuth application on your GitLab instance">
    Go to your GitLab instance's **Admin Area → Applications** (`https://gitlab.yourcompany.com/admin/applications/new`) or **User Settings → Applications** (`https://gitlab.yourcompany.com/-/user_settings/applications`) and create a new application with:

    * **Name**: `Corridor Security`
    * **Redirect URI**: `https://app.corridor.dev/api/auth/gitlab/callback`
    * **Confidential**: Checked
    * **Scopes**: `api`

    Leave **Trusted** unchecked. After saving, copy the **Application ID** and **Secret**.
  </Step>

  <Step title="Connect from Corridor">
    In the Corridor dashboard, go to **Teams** and click **Connect GitLab (Self-Hosted)**. Enter your GitLab instance URL, the Application ID, and the Secret from the previous step.
  </Step>

  <Step title="Authorize Corridor">
    You'll be redirected to your GitLab instance to authorize Corridor. Review the permissions and click **Authorize**.
  </Step>

  <Step title="Select a GitLab group">
    After authorization, select the GitLab group containing the repositories you want to monitor.
  </Step>
</Steps>

## Permissions

Corridor requests the `api` scope from GitLab. This scope is used for both read operations and to set up automated security reviews on your merge requests. Here's what that access covers:

| Resource                  | Usage                                                                       |
| ------------------------- | --------------------------------------------------------------------------- |
| **Groups**                | List available groups during setup                                          |
| **Projects**              | List repositories in your group for import                                  |
| **Repository code**       | Clone and scan code for security analysis                                   |
| **Webhooks**              | Register per-project webhooks to trigger security reviews on merge requests |
| **Merge requests**        | Read MR diffs for security review and post review comments with findings    |
| **Project access tokens** | Create a bot token per project ("Corridor Security") to post MR comments    |

<Note>
  GitLab does not offer granular OAuth scopes for these individual operations, so `api` is the minimum scope required. OAuth tokens are encrypted at rest and automatically refreshed when they expire. Corridor does not store your source code beyond what is needed for analysis.
</Note>

## Importing repositories

<Steps>
  <Step title="Open the Projects page">
    Navigate to **Projects** and click **New Project**.
  </Step>

  <Step title="Select GitLab as the source">
    Select the **GitLab Repository** tab.
  </Step>

  <Step title="Choose a repository">
    Choose a repository from the list, or paste a GitLab repository URL directly.
  </Step>

  <Step title="Wait for setup">
    Corridor will register a webhook on the project, scan the repository, and generate security guardrails.
  </Step>
</Steps>

## Troubleshooting

### Reviews not appearing

1. Verify GitLab is connected in your team settings
2. Check that the project was imported from GitLab (not added manually)
3. Verify the webhook is registered on the GitLab project:
   * Go to your GitLab project → **Settings → Webhooks**
   * Look for a Corridor webhook
   * Check **Recent events** for delivery failures

### Permission errors

1. Reconnect GitLab from **Teams** settings
2. Ensure your GitLab user has at least Maintainer access to the project
3. Verify the project belongs to the connected GitLab group

### Webhook delivery failures

1. Go to the GitLab project → **Settings → Webhooks**
2. Find the Corridor webhook and click **Edit**
3. Check **Recent events** for HTTP errors (4xx, 5xx)
4. If persistent, contact [support@corridor.dev](mailto:support@corridor.dev)

## Next steps

<CardGroup cols={2}>
  <Card title="PR Reviews" icon="code-pull-request" href="/features/pr-reviews">
    Learn more about automated reviews
  </Card>

  <Card title="Guardrails" icon="shield" href="/features/guardrails">
    Configure security guardrails for your project
  </Card>
</CardGroup>