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

# GitLab

> Connect GitLab to ApiTraffic to auto-track commits, tags, and releases

Connecting GitLab authorizes ApiTraffic (via OAuth) to see the projects you belong to and to register push, tag, and release webhooks on the projects you assign to a bucket.

> [!NOTE]
>
> You must be an ApiTraffic account **admin**, and have the **Maintainer** or **Owner** role on any GitLab project you want to track (that role is required to add project webhooks). GitLab.com (cloud) is supported today; self-managed GitLab is not yet.

## 1. Start the connection

In ApiTraffic, go to **Settings → Integrations → Git** and click **Connect GitLab**.

![Connect GitLab button in ApiTraffic git integration settings](https://app.apitraffic.io/images/docs/git/gitlab-connect-button.png)

## 2. Authorize ApiTraffic

You'll be redirected to GitLab to sign in and approve the requested scopes (read your projects and manage their webhooks). Click **Authorize**.

![GitLab OAuth authorization screen for ApiTraffic](https://app.apitraffic.io/images/docs/git/gitlab-authorize.png)

## 3. Assign a project to a bucket

Back in ApiTraffic, your connection now shows as **Active**. Pick a project and choose the **bucket** whose API traffic that code powers. ApiTraffic registers the push/tag/release webhook on that project automatically.

![Assigning a GitLab project to an ApiTraffic bucket](https://app.apitraffic.io/images/docs/git/gitlab-assign-bucket.png)

## 4. Map branches to environments

Add one or more rows mapping a branch (or pattern) to an environment. First matching rule (by priority) wins; you can mark one row as the default fallback.

![Mapping GitLab branches to ApiTraffic environments](https://app.apitraffic.io/images/docs/git/gitlab-branch-mapping.png)

## 5. Verify

Push a commit to a mapped branch. Within a few seconds a `git.push` marker appears on that bucket's charts.

![A git.push marker appearing after a GitLab push](https://app.apitraffic.io/images/docs/git/gitlab-verify-marker.png)

## Disconnecting

* **In ApiTraffic:** Settings → Integrations → Git → **Disconnect** removes the link, deletes the webhooks ApiTraffic created, and stops tracking.
* **In GitLab:** you can also revoke the ApiTraffic authorization under **GitLab → Preferences → Applications**.

## Troubleshooting

> **A project I want isn't listed**
>
> ApiTraffic only lists projects your GitLab user is a member of. Confirm your membership, then refresh the ApiTraffic project list.

> **No marker after pushing**
>
> Confirm the branch you pushed to is mapped to an environment — unmapped branches are intentionally ignored — and that the ApiTraffic webhook still exists under the project's **Settings → Webhooks**.

> **Connection shows an error / expired**
>
> OAuth tokens expire. ApiTraffic refreshes them automatically, but if the refresh fails (for example the authorization was revoked) the connection is marked **Error**. Click **Reconnect** to re-authorize.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.