> For the complete documentation index, see [llms.txt](https://docs.kosmoslabs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kosmoslabs.ai/product-documentation/connecting-gitlab.md).

# Connecting GitLab

***

This guide walks you through connecting GitLab to Kosmos.

Kosmos supports both **GitLab.com** and **self-managed GitLab instances**.

### Prerequisites

* A GitLab account with access to the projects you want to sync
* Admin access to Kosmos to configure the integration

***

### Step 1: Start the Connection

1. In Kosmos, navigate to **Settings → Integrations**
2. Find the **GitLab** card and click **Connect**
3. A dialog appears asking for your GitLab instance URL

***

### Step 2: Enter Your Instance URL

* **GitLab.com:** Leave the default `https://gitlab.com` as-is and click **Continue**
* **Self-managed GitLab:** Replace the default with your instance URL (e.g., `https://gitlab.yourcompany.com`) and click **Continue**

Kosmos validates the URL before proceeding. Private IP addresses and non-HTTPS URLs are not accepted.

***

### Step 3: Authorize via OAuth

1. You'll be redirected to your GitLab instance
2. Review the requested permissions and click **Authorize**
3. You'll be returned to Kosmos with the connection established

GitLab OAuth tokens expire every 2 hours. Kosmos automatically refreshes them in the background — you won't need to reconnect.

***

### Step 4: Select Projects

After connecting, Kosmos displays a project selector.

* Choose the specific projects you want Kosmos to sync
* Leave the selection empty to sync all projects you have access to

Click **Save** when done.

***

### Step 5: Configure Sync Settings

In the sync configuration modal, you can enable or disable each data type:

| Data Type      | What Kosmos syncs                              |
| -------------- | ---------------------------------------------- |
| Issues         | GitLab issues, used as signals for correlation |
| Merge Requests | Merge requests linked to deployments           |
| Commits        | Commit history for deployment correlation      |
| Pipelines      | Pipeline runs correlated with incidents        |
| Deployments    | Deployment events tied to incidents            |

All types are enabled by default. Adjust as needed and click **Save Settings**.

***

### Step 6: Verify the Connection

Once saved, Kosmos begins syncing data from your selected GitLab projects.

Navigate to the **Signals** tab to confirm events are flowing in from your connected instance.

***

### Revoking Access

**From Kosmos:** Settings → Integrations → GitLab → Disconnect

**From GitLab:** User Settings → Applications → Revoke Kosmos access

***

### Data Access

For details on what Kosmos reads from GitLab, see [Integration Permissions](/product-documentation/integration-permissions.md#gitlab).

All access is **read-only**. Kosmos never creates, updates, or deletes any records in your GitLab instance.

***

**Questions?** Contact <support@kosmoslabs.ai> | [app.kosmoslabs.ai](https://app.kosmoslabs.ai/)

© 2026 Kosmos AI Labs, Inc.