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

# GitLab

> Connect a GitLab group to NOFire AI for code context and change events

Connect a GitLab group to NOFire AI so investigations and chat can read your code, commits and merge requests, and so pushes, merge requests, releases and deployments show up as change events. NOFire AI works with GitLab.com and with self-managed GitLab.

## What this enables

* **Code context**: search repositories and code, read files, commits, merge requests and diffs, and compare refs during investigations and in chat.
* **Change events**: pushes, tag pushes, merge requests, releases and deployments arrive through a group webhook and are correlated with production behavior.

NOFire AI has read-only access. It does not push code or open merge requests.

## Prerequisites

* A GitLab group on **Premium** or **Ultimate**. Group access tokens and group webhooks are not available on GitLab Free.
* The **Owner** role in that group, to create the token and the webhook.
* For self-managed GitLab:
  * The instance must be reachable from NOFire AI. Use HTTPS with a publicly trusted certificate: over HTTP, the token is sent in plaintext. If you restrict inbound traffic, contact [support@nofire.ai](mailto:support@nofire.ai) for the addresses to allow.
  * The instance must be able to reach NOFire AI, to deliver webhooks. If you restrict outbound traffic, allow the host in the NOFire AI webhook URL from Step 3.

## Step 1: Create a group access token

> [accordion] Generate a group access token in GitLab
>
> 1. In GitLab, open the group you want NOFire AI to read. NOFire AI reads every project in the group and its subgroups.
> 2. Go to **Settings** → **Access tokens** and click **Add new token**.
> 3. Name the token, for example `NOFire AI`, and set an expiration date.
> 4. Select the **Reporter** role.
> 5. Select the `read_api` and `read_repository` scopes. The `api` scope also works, but grants more than NOFire AI needs.
> 6. Create the token and copy it. GitLab shows it only once. You enter it in Step 2.

## Step 2: Add the GitLab connection in NOFire AI

> [accordion] Configure the connection
>
> 1. Open [Connections](https://my.nofire.ai/dashboard/connections) and click **Connect** on **GitLab**.
>
>    ![GitLab in the NOFire AI connection catalog](https://mintcdn.com/nofireai/JxwUwUMgFFlpMJMS/images/gitlab/catalog.png?fit=max\&auto=format\&n=JxwUwUMgFFlpMJMS\&q=85\&s=51d237293422a5908f23f30466b2f8d8)
> 2. Enter:
>
>    * **Name**, for example `gitlab-acme`
>    * **GitLab URL**: the address you open GitLab at, without `/api/v4`. For example `https://gitlab.com` or `https://gitlab.example.com`.
>    * **Group path**: the group or subgroup as it appears in its URL, for example `acme/platform`
>    * **Group access token**: the token from Step 1
>
>    ![GitLab connection form](https://mintcdn.com/nofireai/JxwUwUMgFFlpMJMS/images/gitlab/form.png?fit=max\&auto=format\&n=JxwUwUMgFFlpMJMS\&q=85\&s=d8b7996f311034a2a42f969c96c06347)
> 3. Click **Test connection**. NOFire AI checks the token's scopes and expiry and that it can see the group. A passing test shows **Token and group accepted**.
>
>    ![GitLab connection form after a successful test](https://mintcdn.com/nofireai/JxwUwUMgFFlpMJMS/images/gitlab/form-tested.png?fit=max\&auto=format\&n=JxwUwUMgFFlpMJMS\&q=85\&s=51aca660271f673cb0a90b97976f8205)
> 4. Click **Connect**.

## Step 3: Add the group webhook

The webhook sends change events to NOFire AI. Without it, code context still works, but no change events arrive.

> [accordion] Create the webhook secret in NOFire AI
>
> 1. In [Connections](https://my.nofire.ai/dashboard/connections), find the GitLab connection and click **Manage**.
> 2. Click **Create webhook secret**. NOFire AI shows the **Webhook URL** and the **Secret token**.
>
>    ![GitLab webhook URL and secret token in NOFire AI](https://mintcdn.com/nofireai/JxwUwUMgFFlpMJMS/images/gitlab/webhook-panel.png?fit=max\&auto=format\&n=JxwUwUMgFFlpMJMS\&q=85\&s=4623008da6784a2bc9d0fb08562ada4f)

> [accordion] Add the webhook in GitLab
>
> 1. In GitLab, open the same group and go to **Settings** → **Webhooks** → **Add new webhook**.
> 2. Paste the NOFire AI webhook URL into **URL** and the secret into **Secret token**.
> 3. Under **Trigger**, select:
>    * **Push events**
>    * **Tag push events**
>    * **Merge request events**
>    * **Releases events**
>    * **Deployment events**
> 4. Keep **Enable SSL verification** on, then click **Add webhook**.

To replace the secret, click **Rotate secret** in the same panel and paste the new secret into the GitLab webhook. Events signed with the old secret are rejected from then on.

## Test the connection

1. Open [Connections](https://my.nofire.ai/dashboard/connections) and make sure that the GitLab connection shows **Connected**. A connection that shows **Failing** did not authenticate.
2. In GitLab, open the webhook and click **Test** → **Push events**. In NOFire AI, **Last event** in the connection's webhook panel updates to the time of the test.
3. Ask NOFire AI about a recent merge request in one of the group's projects. An answer that names it confirms that code access works.

## Troubleshooting

> [accordion] GitLab did not accept the token
>
> The token is wrong, expired or revoked. Create a new group access token and update the connection.

> [accordion] The GitLab token is missing required scopes
>
> Create a new group access token with the `read_api` and `read_repository` scopes. GitLab does not let you add scopes to an existing token.

> [accordion] GitLab group not found, or the token cannot see it
>
> Check that **Group path** matches the group's URL, and that the token was created in that group or a parent group.

> [accordion] The connection test warns that the token expires soon
>
> The connection stops working when the token expires. Create a new token before then and update the connection.

> [accordion] No events arrive
>
> Check that the webhook is on the group connected to NOFire AI, that its triggers include the events above, and that the secret token matches the one in NOFire AI. On self-managed GitLab, also check that the instance can reach NOFire AI through your firewall. GitLab lists each delivery and its response or error under the webhook's **Recent events**.

Any questions? Contact us at [support@nofire.ai](mailto:support@nofire.ai).


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