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

# Connect to GitLab

> Connect Overcut to GitLab.com or a self-hosted GitLab instance so your workspace can work with repositories, issues, merge requests, and GitLab-triggered workflows.

## What You Can Do

With GitLab connected, Overcut agents can:

* **Access repositories** to clone, read, and update code
* **Manage issues** by creating, updating, and commenting on GitLab issues
* **Handle merge requests** by reviewing, commenting on, and managing merge requests
* **Run code operations** such as cloning repositories and creating branches
* **Use webhook triggers** to start workflows from GitLab events
* **Configure repositories** for workspace-specific automation

## Prerequisites

Before you connect GitLab, make sure you have:

* A **GitLab account** on GitLab.com or on your self-hosted GitLab instance
* An active Overcut workspace
* A **dedicated GitLab service account** with **Maintainer** or **Owner** access to the repositories or groups you want Overcut to use

If you plan to connect a self-hosted GitLab instance, also make sure you have:

* Your **GitLab instance URL** such as `https://gitlab.example.com`, served over **HTTPS** with a **valid (non self-signed) TLS certificate**
* The GitLab instance is **reachable from Overcut** over the public internet so Overcut can complete the OAuth token exchange and call the GitLab API
* If you plan to use GitLab **event triggers**, the GitLab instance can also send **outbound webhooks to Overcut** at `https://app.overcut.ai`
* An **OAuth Application ID** created in that GitLab instance
* An **OAuth Application Secret** created in that GitLab instance
* Access to sign in to that GitLab instance as the service account during setup

<Note>
  Use a dedicated service account instead of a personal account. This keeps your bot identity consistent, avoids permission changes when teammates leave, and makes automated activity easier to recognize.
</Note>

## Connection options

You can connect GitLab to Overcut in two ways:

<CardGroup cols={2}>
  <Card title="GitLab.com" icon="cloud">
    Use this option if your repositories are hosted on GitLab.com. You only need
    the service account and GitLab.com sign-in.
  </Card>

  <Card title="Self-hosted GitLab" icon="server">
    Use this option if your team runs GitLab on your own domain or private
    infrastructure. You will enter your instance URL and your instance-specific
    OAuth application credentials before authorizing access.
  </Card>
</CardGroup>

## Choose GitLab.com or self-hosted GitLab

In Overcut, go to **Integrations** and start the GitLab connection flow.

* Leave **Connect to a self-hosted GitLab instance** turned off if you use **GitLab.com**
* Turn on **Connect to a self-hosted GitLab instance** if you use your own **GitLab domain or private deployment**

When you choose the self-hosted option, Overcut asks for three fields before you continue:

* **Instance URL**
* **OAuth Application ID**
* **OAuth Application Secret**

These values are specific to your GitLab instance and are different from the standard GitLab.com flow.

## Connect a self-hosted GitLab instance

<Steps>
  <Step title="Prepare your GitLab service account">
    Create or choose a dedicated GitLab user for Overcut, then add that account
    to the projects or groups you want to connect.

    Give the account **Maintainer** or **Owner** access to the repositories and
    groups you want Overcut to use so it can work with repositories, issues,
    merge requests, and GitLab-triggered workflows.
  </Step>

  <Step title="Register an instance-wide OAuth application in GitLab">
    Overcut connects to self-hosted GitLab using an **instance-wide OAuth
    application** that a GitLab administrator registers in your GitLab
    instance. This step gives Overcut the **Application ID** and **Application
    Secret** it needs, and keeps the integration owned by the organization
    rather than an individual user or group.

    <Note>
      An instance administrator must perform this step. If you are not a GitLab
      administrator, coordinate with the team that manages your GitLab
      instance.
    </Note>

    In your self-hosted GitLab instance, go to the **Admin area →
    Applications** and select **New application**. For full instructions and
    screenshots, see GitLab's official documentation on [configuring GitLab
    as an OAuth 2.0 authentication identity provider](https://docs.gitlab.com/integration/oauth_provider/).

    Use these settings when creating the application:

    * **Name**: any recognizable label such as `Overcut`
    * **Redirect URI** (labeled **Callback URL** in GitLab's admin UI): `https://app.overcut.ai/gitlab-auth-app/callback`
    * **Trusted**: leave disabled
    * **Confidential**: enabled
    * **Scopes**: select **`api`**

    After you save the application, GitLab displays the **Application ID** and
    **Secret**. Copy both values. You will paste them into Overcut in the
    next step.

    <Warning>
      GitLab typically shows the Application Secret only once. Store it
      securely when you first see it; if you lose it, you will need to
      regenerate the secret in GitLab and update Overcut.
    </Warning>
  </Step>

  <Step title="Enter the self-hosted connection details in Overcut">
    In **Integrations**, choose **GitLab**, enable **Connect to a self-hosted
    GitLab instance**, and enter:

    * **Instance URL**
    * **OAuth Application ID**
    * **OAuth Application Secret**

    Then select **I am ready to continue**.
  </Step>

  <Step title="Authorize access in your GitLab instance">
    Overcut redirects you to your **own GitLab instance** for authorization.

    Sign in as the dedicated service account if needed, review the request, and
    approve access to complete the connection.
  </Step>
</Steps>

## Verify the connection

After authorization, confirm the connection is working as expected:

* Open your repository list in Overcut and confirm the expected GitLab repositories appear
* Start creating or editing a workflow and verify you can select the connected GitLab repositories or projects
* If you use GitLab event triggers, create a simple test change such as opening an issue, commenting on an issue, updating a merge request, or running a pipeline and confirm the workflow can respond

<Tip>
  If you manage more than one GitLab environment, confirm that the repositories shown in Overcut belong to the same instance URL you entered during setup.
</Tip>

## Troubleshooting

If the connection does not work as expected, check the following:

* **Wrong instance URL**: Confirm you entered the full URL for the correct GitLab instance
* **Wrong OAuth credentials**: Make sure the Application ID and Application Secret come from the same self-hosted GitLab instance you are connecting
* **Callback URL mismatch**: If GitLab shows an "invalid redirect URI" error during authorization, edit the OAuth application in GitLab and set the **Callback URL** to exactly `https://app.overcut.ai/gitlab-auth-app/callback`.
* **Missing `api` scope**: The OAuth application must have the **`api`** scope selected. If it is missing, edit the application in GitLab, enable the scope, and try connecting again.
* **Signed in to the wrong account**: Complete authorization using the dedicated GitLab service account, not a personal account with limited access
* **Missing repository or group access**: Verify the service account has **Maintainer** or **Owner** access to the repositories or groups you want to use in Overcut
* **Unexpected redirect destination**: For self-hosted connections, authorization should redirect to your own GitLab domain rather than GitLab.com

If you still cannot complete setup, repeat the connection flow and re-enter the instance URL and OAuth application credentials carefully.

## GitLab.com vs self-hosted GitLab

| Connection type        | What you enter in Overcut                                        | Where authorization happens |
| ---------------------- | ---------------------------------------------------------------- | --------------------------- |
| **GitLab.com**         | No instance-specific fields                                      | GitLab.com                  |
| **Self-hosted GitLab** | Instance URL, OAuth Application ID, and OAuth Application Secret | Your GitLab instance        |

Use GitLab.com when your repositories are hosted on GitLab.com. Use the self-hosted option when your team uses GitLab on a private domain or managed infrastructure.

## What happens after connection

Once the connection is complete, Overcut uses the GitLab account and instance you connected for GitLab-related work in your workspace.

This means Overcut can use that GitLab instance to:

* Access connected repositories
* Work with issues and merge requests
* Support GitLab-based workflow activity
* Respond to supported GitLab events for connected repositories, including issues, issue comments, merge requests, merge request comments, and pipeline activity

If you connected a self-hosted GitLab instance, Overcut continues to use that configured instance for repository access and related GitLab activity in your workflows.

## Issue links in GitLab

Agents can create, remove, and read GitLab issue links. GitLab supports three link types: `relates_to`, `blocks`, and `is_blocked_by` (agents can inspect the available types before linking). Cross-project linking works when GitLab allows it and the service account can access both projects. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers.

## Using GitLab in Your Workflows

Once connected, GitLab repositories will appear as available sources when you:

* Add a **Source** to a workflow
* Configure a **Trigger** that monitors GitLab events
* Set up **Actions** that work with code or issues

## Permissions

The GitLab OAuth integration requests the following scope:

### API access

* **`api`**: Access needed to work with repositories, issues, merge requests, and related GitLab actions in Overcut