# Connect GitLab

> Authorize ApiTraffic on gitlab.com, link a project to a bucket and map branches to environments so pushes, tags and releases become event markers.

Source: https://www.apitraffic.io/docs/git-integrations/gitlab

Connecting GitLab authorizes ApiTraffic, through OAuth, to see your projects and to add a webhook for push, tag and release events to each project you link. Only gitlab.com is supported; self-managed GitLab is not.

## Before you begin

- You are an ApiTraffic account **owner** or **admin**.
- On GitLab, you have the **Maintainer** or **Owner** role on each project you want to track. That role is needed to add a project webhook.
- Your plan includes **Git integration**. See [Git integrations](https://www.apitraffic.io/docs/git-integrations/overview#before-you-begin).

## Connect GitLab

**Start the connection**

Open the account menu, choose **Account**, then select **Git** under **Integration**. In **Connect a Provider**, select **Connect GitLab**.

**Authorize ApiTraffic on GitLab**

GitLab asks you to sign in and approve ApiTraffic's access. Approve it.

**Return to ApiTraffic**

GitLab sends you back to **Git Integration**, which shows **Git provider connected.** The GitLab card shows your GitLab account and the status `active`.

**Link a project**

On the GitLab card, select **Add Repository**. Choose the project under **Repository** and the **Bucket** whose traffic it serves, keep the **Subscribed events** you want, and select **Link Repository**. ApiTraffic adds the webhook to the project.

**Map branches to environments**

Under **Branch → Environment mappings**, add a row for each branch that deploys and select **Add**. The first matching mapping by priority wins; you can mark one as **Fallback**.

**Verify**

Push a commit to a mapped branch. Within a few seconds a `git.push` marker appears on the bucket's charts. If it doesn't, select **Diagnose**.

## How GitLab diagnostics work

**Diagnose** checks that the GitLab access token works, that it can reach the project, that ApiTraffic's webhook is still on the project, and the deliveries ApiTraffic has received. If the webhook is missing, for example because someone deleted it, select **Re-register webhook**.

## Disconnect

- **In ApiTraffic:** select **Disconnect** on the GitLab card. All of its projects are unlinked, and ApiTraffic removes the webhooks it added where it still can.
- **On GitLab:** you can also revoke ApiTraffic's access in your GitLab user settings under **Applications**.

## Troubleshooting

**A project I want isn't listed**

ApiTraffic lists the projects your GitLab user is a member of. Check your membership, then open **Add Repository** again.

**No marker after pushing**

Select **Diagnose**. Check that the branch matches a mapping, and that the webhook still exists under the project's **Settings** → **Webhooks**.

**The connection shows error**

ApiTraffic refreshes GitLab tokens automatically, but if a refresh fails, for example because access was revoked, the connection is marked `error`. Connect GitLab again, link the projects under the new connection, then disconnect the old one.

## Related

- [Git integrations](https://www.apitraffic.io/docs/git-integrations/overview):
    Branch mappings, marker types and health checks.

- [Event markers](https://www.apitraffic.io/docs/events):
    How markers appear on charts.