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

# GitLab

> Set up a GitLab webhook to capture pushes, merge requests, issues, pipelines, and deployments in your knowledge graph.

The GitLab integration captures repository activity: pushes, merge requests, issues, comments, releases, pipelines, and deployments. This is how Cogniscape connects delivery work to your knowledge graph — **what** changed, **who** did it, **how** it was done, and **when** it happened.

You can configure the webhook for a single **project**, or at the **group** level to capture every project and subgroup at once.

<Note>
  Group webhooks require **GitLab Premium or Ultimate**. On the Free tier, configure one webhook per project.
</Note>

<Warning>
  **We never store any source code.** Cogniscape only processes event metadata — commit hashes, merge request titles, comments, and similar structured data. Your code stays on GitLab. See [Data Privacy](/security/data-privacy) for details.
</Warning>

## Configure the webhook

<Steps>
  <Step title="Open your webhook settings">
    In the top bar, find your project or group. In the left sidebar, select **Settings → Webhooks**, then select **Add new webhook**.
  </Step>

  <Step title="Add a name">
    Use a descriptive name such as **Cogniscape** so you can identify it later.
  </Step>

  <Step title="Paste the webhook URL">
    Use the following URL, replacing `<your-customer-key>` with the key from the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab):

    ```
    https://api.cogniscape.app/api/v1/events/gitlab/key/<your-customer-key>
    ```

    <Tip>
      The portal shows the URL already filled in with your key — copy it straight from there instead of assembling it by hand.
    </Tip>
  </Step>

  <Step title="Generate and save the signing token">
    Under **Request authentication**, select **Generate signing token**.

    <Warning>
      GitLab displays the signing token **only once**. Copy it before leaving the page — if you lose it, you have to generate a new one.
    </Warning>

    Paste the token into the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab) under **Get Started → GitLab Webhook → step 4** and select **Save token**. Cogniscape uses it to verify that incoming events are genuinely from GitLab.

    <Note>
      Do **not** use the legacy **Secret token** field for a new webhook. Cogniscape verifies GitLab deliveries using the Standard Webhooks signature, which requires the signing token.
    </Note>
  </Step>

  <Step title="Choose the events to send">
    Select these events so Cogniscape receives the development activity it supports:

    * Push events
    * Tag push events
    * Merge request events
    * Issue events (Issue Hook, including Work Items)
    * Comment events (Note Hook)
    * Release events
    * Pipeline events
    * Deployment events
  </Step>

  <Step title="Add and test the webhook">
    Select **Add webhook**. From the webhook list, open **Test** and send a **Push events** test.

    Confirm the test succeeds in GitLab, then return to the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab) and check that the signing token shows as saved.
  </Step>
</Steps>

## Verify the webhook

After saving, GitLab records every delivery under **Settings → Webhooks → Edit → Recent events**. A `200` response confirms Cogniscape received and verified the event.

Common failure responses:

| Response                    | What it means                                                                                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`          | The signing token in the portal does not match the one GitLab is signing with, or the delivery timestamp is outside the 5-minute replay window. Regenerate the token in GitLab and re-save it in the portal. |
| `403 Forbidden`             | The customer key in the URL is invalid or the account is disabled.                                                                                                                                           |
| `422 Unprocessable Content` | The `X-Gitlab-Event` header is missing or the payload is malformed — usually a sign the URL was pasted into the wrong integration.                                                                           |

## Supported events

Cogniscape processes these GitLab webhook event types:

| Event                | What it captures                                                           |
| -------------------- | -------------------------------------------------------------------------- |
| Push events          | Commits pushed to any branch — who committed, when, and to which branch    |
| Tag push events      | Tags created or deleted — release checkpoints in the delivery timeline     |
| Merge request events | MR creation, updates, merges, and closures — the full lifecycle            |
| Issue events         | Issue and Work Item creation, updates, assignments, labeling, and closures |
| Comment events       | Comments on merge requests, issues, commits, and code snippets             |
| Release events       | Releases published, updated, and deleted                                   |
| Pipeline events      | Pipeline runs — status, duration, and outcome                              |
| Deployment events    | Deployment status notifications — success, failure, and running states     |

<Note>
  Events not listed above are received but silently ignored. Enabling extra event types is safe — it won't create noise in your knowledge graph.
</Note>

## Project vs group webhooks

A **group webhook** covers every project and subgroup underneath it, including projects created later. This is the recommended setup if your plan supports it — you configure it once and new repositories are captured automatically.

A **project webhook** covers a single project. On GitLab Free, repeat the setup for each project you want to observe.

Both use the same webhook URL. The customer key routes all events to the correct knowledge graph regardless of which project or group sends them.

<Tip>
  You can mix both. If a project already has its own webhook and later falls under a group webhook, Cogniscape deduplicates deliveries — the same event won't be ingested twice.
</Tip>

## Why the signing token matters

GitLab signs every webhook payload using the [Standard Webhooks](https://www.standardwebhooks.com/) scheme: an HMAC-SHA256 signature over the delivery ID, timestamp, and raw body, sent in the `webhook-signature` header. Cogniscape verifies this signature before processing any event, and rejects deliveries whose timestamp is more than **5 minutes** old to prevent replay attacks.

Each customer has their own unique token. This means:

* A leaked token only affects your tenant — it cannot be used to forge events for other customers.
* You can rotate the token at any time from GitLab without coordinating across customers.
* Ex-employees or compromised systems can be cut off by rotating, without disrupting other tenants.

<Warning>
  Rotating the token in GitLab invalidates the previous one **immediately**. Save the new token in the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab) as soon as you rotate, or events will fail signature verification with `401` until the new token is in place.
</Warning>

Full GitLab reference: [Webhooks documentation](https://docs.gitlab.com/user/project/integrations/webhooks/).