# GitLab

EvoHub receives GitLab events through a project or group **webhook**, on GitLab.com or your own GitLab. It pages when the default branch's pipeline or a deployment fails, and resolves when the next one succeeds.

## Set it up

:::steps
### Create the integration
In EvoHub, go to **On-Call → Integrations → + Add Integration**, choose **GitLab**, pick an **Escalation Policy** and click **Create Integration**. Copy the **Webhook URL**.
### Generate a signing secret
Open the integration and, under **Signing secret**, click **Generate secret**. Copy it — it is shown once.
### Add the webhook
In GitLab, open the project (or group) **Settings → Webhooks → Add new webhook**. Set **URL** to your webhook URL and **Secret token** to the signing secret.
### Choose the triggers
Tick **Pipeline events** or **Job events**, and **Deployment events** if you deploy with GitLab environments. Click **Add webhook**.
:::

Pick **Pipeline events** for one page per failed pipeline, or **Job events** for one page per failed job. Ticking both pages for both. GitLab's **Test** button replays your latest event of that kind, so testing with a failed default-branch pipeline opens a real alert.

> [!TIP]
> On GitLab 19.1 and later a webhook can have a **Signing token** (`whsec_…`) instead of a secret token. Paste that value into **Use my own** under the integration's signing secret; EvoHub checks the signature and refuses deliveries more than five minutes old.

## What pages

| GitLab event | Opens an alert when | Severity | Resolves when |
| --- | --- | --- | --- |
| Pipeline events | a pipeline on the project's default branch fails | high | the next pipeline on that branch succeeds |
| Job events | a job on the default branch fails and is not allowed to fail | high | the same job on that branch succeeds |
| Deployment events | a deployment fails | critical for the production tier, high otherwise | the next deployment to the same environment succeeds |

Child pipelines are left to their parent, which fails with them. Tags, other branches, pushes, merge requests and every other event are answered `200` and open nothing — GitLab disables a webhook after four failed deliveries in a row, so EvoHub only refuses a malformed body, a wrong key or a wrong secret.

GitLab has no webhook for its own alerts, so those are not received.

## What EvoHub reads

| EvoHub alert | Taken from |
| --- | --- |
| Title | What failed, where, and the project path — for example *Pipeline failed on main (acme/shop)*. |
| Description | The pipeline number, the job and stage with GitLab's failure reason, or the deployment and its commit title. |
| Labels | `project`, `event`, `ref`, `commit`, and per event `pipeline_source`, `job`, `stage`, `failure_reason`, `environment`, `environment_tier`, and `url` — a link to the pipeline, job or deployment job. |

## Resolve and deduplication

An alert is identified by the project and the branch, the branch and job, or the environment. While it is open, another failure is recorded as **Retriggered** instead of paging again.

## Signature

With a signing secret set, every delivery must carry it as `X-Gitlab-Token`, or be signed with it in `webhook-signature`. Anything else is refused with `403` and opens nothing. See [Signing secrets](https://docs-dev.evohub.io/integrations-overview.md#signing-secrets).

## Related

- [Integrations overview](https://docs-dev.evohub.io/integrations-overview.md)
- [GitHub](https://docs-dev.evohub.io/github.md)
- [Jenkins](https://docs-dev.evohub.io/jenkins.md)