> 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/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](/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kosmoslabs.ai/connecting-gitlab.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.