> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/deployment-integrations/gitlab.md).

# GitLab deployment pipeline

Send GitLab pushes, merge requests and releases to ilert, so alerts arrive with the change that most likely caused them.

A GitLab webhook posts pushes, merge requests, and releases to ilert, which records them as deployment events and attaches the closest ones to alerts that fire shortly afterwards.

Set the webhook on a **group** to cover every project inside it at once, or on a single project. The form is the same either way; only where you find it differs.

## Create the pipeline

Follow [Create a deployment pipeline](/integrations/deployment-integrations.md#create-a-deployment-pipeline) and choose type **GitLab**. You need the **URL** from the pipeline's detail view for the steps below, and two of its settings decide what actually gets recorded:

* **Branch filters** arrive prefilled with `main` and `master`. Pushes to other branches are dropped. Clear the field to keep them all.
* **Event filters** — *Push hook*, *Merge request hook*, *Release hook* — narrow what is kept. Empty means everything GitLab sends.

{% hint style="info" %}
Prefer **Release hook** where you cut releases. Push events from a group-wide webhook can arrive hundreds a day, and a correlation that matches everything explains nothing.
{% endhint %}

## Set up the webhook

{% stepper %}
{% step %}

### Open the hooks page

For a group: **Settings** → **Webhooks** in the group's sidebar. For a single project: **Settings** → **Webhooks** in the project's.

<figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2F919qs9xdB85VNBOeB8eW%2F7.png?alt=media&amp;token=b2ffdeb8-be3b-418a-922c-d076468c7f0b" alt="The GitLab group settings menu expanded, with Webhooks among the entries."><figcaption><p>Group settings cover every project inside the group.</p></figcaption></figure>

<figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2FvommUdnvSu7bq2WlxhqX%2F8.png?alt=media&amp;token=193d50ea-2e8d-4a24-bc21-105f143e67c1" alt="The GitLab Group hooks page with no webhooks configured and an Add new webhook button."><figcaption><p>Click <strong>Add new webhook</strong>.</p></figcaption></figure>
{% endstep %}

{% step %}

### Paste the ilert URL

Put the pipeline's **URL** into **URL**. Leave **Secret token** empty — ilert authenticates on the integration key already in the URL.

<figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2FprEPrTkzNiVJ2GSeaorT%2F9.png?alt=media&amp;token=32a5303d-012e-4263-8807-153896f558f5" alt="The GitLab webhook URL field holding an ilert deployment pipeline URL, with the integration key blurred out."><figcaption><p>Because the key travels in the URL, <strong>Mask portions of URL</strong> is worth turning on afterwards.</p></figcaption></figure>
{% endstep %}

{% step %}

### Choose the trigger events

Scroll to **Trigger** and tick the events you want — **Push events**, **Merge request events**, and **Releases events** between them cover what ilert can correlate. Tick generously and narrow later in the pipeline's event filters, which does not require touching GitLab again.

<figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2Fkp6KtcodFWSO6MaZ7o2Z%2F10-1.png?alt=media&amp;token=e0dacccf-40bd-47c7-b688-e1427c066d53" alt="The GitLab Push events trigger, with branch scope options for all branches, a wildcard pattern, or a regular expression."><figcaption><p>Leave the branch scope at <em>All branches</em> and let ilert's branch filters do the narrowing, so both filters live in one place.</p></figcaption></figure>

<figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2FfT0kMjUvcwWIdAm361jJ%2F10-2..png?alt=media&amp;token=30ba3635-0250-46ac-b427-9eef5e22f507" alt="The GitLab Merge request events trigger, described as firing when a merge request is created, updated, or merged."><figcaption><p>ilert records the merge, not every update.</p></figcaption></figure>

<figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2Ftf2VJTnI22uxE0VLdBQX%2F10-3.png?alt=media&amp;token=187b9b54-707b-4ac6-b9a3-f86b543156da" alt="The GitLab Releases events trigger, described as firing when a release is created, updated, or deleted."><figcaption><p>The one to prefer if you cut releases.</p></figcaption></figure>
{% endstep %}

{% step %}

### Add it and confirm

Click **Add webhook**, then push a commit or publish a release and check that a row appears under **Alerting** → **Deployment events** in ilert. GitLab's **Recent events** view on the webhook shows the response ilert returned.
{% endstep %}
{% endstepper %}


---

# 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.ilert.com/integrations/deployment-integrations/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.