> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/ai-sre/ai-sre-for-administrators/set-up-alert-management/webhooks/integration-guides/cicd/gitlab.md).

# GitLab Integration Guide

Configure GitLab project or group webhooks to send event notifications to Harness AI SRE for deployments, pipelines, and security alerts.

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Harness webhook endpoint**: Create a GitLab webhook in Harness AI SRE using the [GitLab webhook template](/ai-sre/ai-sre-for-administrators/set-up-alert-management/webhooks/templates/cicd/gitlab.md).
* **GitLab permissions**: Maintainer or Owner role for the project/group.
* **Webhook URL**: Copy the webhook URL from your Harness webhook configuration.
* **GitLab webhooks documentation**: Go to [Webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) for webhook configuration guide.
* **Webhook events reference**: Go to [Webhook Events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html) for event-specific payload structures.

***

### Create project webhook <a href="#create-project-webhook" id="create-project-webhook"></a>

#### Navigate to webhook settings <a href="#navigate-to-webhook-settings" id="navigate-to-webhook-settings"></a>

{% tabs %}
{% tab title="Project webhook" %}

1. Go to your GitLab project
2. Click **Settings**, then click **Webhooks**
3. Expand **Add new webhook**
   {% endtab %}

{% tab title="Group webhook" %}

1. Go to your GitLab group
2. Click **Settings**, then click **Webhooks**
3. Click **Add new webhook**

Group webhooks receive events from all projects in the group.
{% endtab %}
{% endtabs %}

#### Configure webhook <a href="#configure-webhook" id="configure-webhook"></a>

{% tabs %}
{% tab title="Basic configuration" %}

* **URL**: Your Harness webhook URL

  ```
  https://<your-harness-instance>/gateway/ai-sre/api/webhooks/<webhook-id>
  ```
* **Secret token**: (Optional) Sent as plain text for token comparison, not cryptographic signature verification
* **Trigger**: Select events to trigger webhook
* **SSL verification**: Enable SSL verification
  {% endtab %}

{% tab title="With secret validation" %}

* **URL**: Your Harness webhook URL
* **Secret token**: Enter a secure token
  * GitLab sends this in `X-Gitlab-Token` header
  * Harness can verify this header
* **Trigger**: Select events
* **SSL verification**: Enable
  {% endtab %}

{% tab title="Custom event selection" %}

* **URL**: Your Harness webhook URL
* **Trigger**: Select specific events

Common events for monitoring:

* ☑ Push events
* ☑ Tag push events
* ☑ Merge request events
* ☑ Pipeline events
* ☑ Deployment events
* ☑ Releases events
* ☐ Issues events (optional)
* ☐ Confidential issues events
* ☐ Merge request approval events
* ☐ Job events (optional)
  {% endtab %}
  {% endtabs %}

#### Test webhook <a href="#test-webhook" id="test-webhook"></a>

Click **Test**, select the event type, then click the **Test** button.

GitLab sends a test payload to verify the webhook is reachable.

#### Add webhook <a href="#add-webhook" id="add-webhook"></a>

Click **Add webhook** to save.

***

### Configure field mapping in Harness <a href="#configure-field-mapping-in-harness" id="configure-field-mapping-in-harness"></a>

#### GitLab webhook payload structure <a href="#gitlab-webhook-payload-structure" id="gitlab-webhook-payload-structure"></a>

{% tabs %}
{% tab title="Pipeline event" %}

```json
{
  "object_kind": "pipeline",
  "object_attributes": {
    "id": 123,
    "ref": "main",
    "tag": false,
    "sha": "abc123def456",
    "before_sha": "def456abc123",
    "source": "push",
    "status": "failed",
    "detailed_status": "failed",
    "stages": ["build", "test", "deploy"],
    "created_at": "2025-07-01 10:30:00 UTC",
    "finished_at": "2025-07-01 10:35:00 UTC",
    "duration": 300,
    "variables": []
  },
  "user": {
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com"
  },
  "project": {
    "id": 456,
    "name": "my-app",
    "description": "My application",
    "web_url": "https://gitlab.com/mygroup/my-app",
    "path_with_namespace": "mygroup/my-app"
  },
  "commit": {
    "id": "abc123def456",
    "message": "Fix production bug",
    "title": "Fix production bug",
    "timestamp": "2025-07-01T10:30:00Z",
    "url": "https://gitlab.com/mygroup/my-app/-/commit/abc123def456",
    "author": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  "builds": [
    {
      "id": 789,
      "stage": "deploy",
      "name": "deploy_production",
      "status": "failed",
      "created_at": "2025-07-01 10:33:00 UTC",
      "started_at": "2025-07-01 10:33:05 UTC",
      "finished_at": "2025-07-01 10:35:00 UTC",
      "when": "on_success",
      "manual": false,
      "allow_failure": false,
      "user": {
        "name": "John Doe",
        "username": "johndoe",
        "email": "john@example.com"
      },
      "runner": null,
      "environment": {
        "name": "production",
        "action": "start"
      }
    }
  ]
}
```

{% endtab %}

{% tab title="Deployment event" %}

```json
{
  "object_kind": "deployment",
  "status": "failed",
  "status_changed_at": "2025-07-01 10:35:00 UTC",
  "deployment_id": 123,
  "deployable_id": 789,
  "deployable_url": "https://gitlab.com/mygroup/my-app/-/jobs/789",
  "environment": "production",
  "project": {
    "id": 456,
    "name": "my-app",
    "description": "My application",
    "web_url": "https://gitlab.com/mygroup/my-app",
    "path_with_namespace": "mygroup/my-app"
  },
  "short_sha": "abc123d",
  "user": {
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com"
  },
  "user_url": "https://gitlab.com/johndoe",
  "commit_url": "https://gitlab.com/mygroup/my-app/-/commit/abc123def456",
  "commit_title": "Fix production bug"
}
```

{% endtab %}

{% tab title="Release event" %}

```json
{
  "id": 123,
  "created_at": "2025-07-01T10:30:00Z",
  "description": "Release notes here",
  "name": "v1.2.3",
  "released_at": "2025-07-01T10:30:00Z",
  "tag": "v1.2.3",
  "object_kind": "release",
  "project": {
    "id": 456,
    "name": "my-app",
    "description": "My application",
    "web_url": "https://gitlab.com/mygroup/my-app",
    "path_with_namespace": "mygroup/my-app"
  },
  "url": "https://gitlab.com/mygroup/my-app/-/releases/v1.2.3",
  "action": "create",
  "assets": {
    "count": 4,
    "links": [],
    "sources": []
  },
  "commit": {
    "id": "abc123def456",
    "message": "Release v1.2.3",
    "title": "Release v1.2.3",
    "timestamp": "2025-07-01T10:30:00Z",
    "url": "https://gitlab.com/mygroup/my-app/-/commit/abc123def456",
    "author": {
      "name": "Release Bot",
      "email": "bot@example.com"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Field mapping by event type <a href="#field-mapping-by-event-type" id="field-mapping-by-event-type"></a>

{% tabs %}
{% tab title="Pipeline event" %}

```cel
title: "Pipeline " + webhook.object_attributes.status + ": " + webhook.project.path_with_namespace
message: "Pipeline for " + webhook.object_attributes.ref + " " + webhook.object_attributes.status + "\n\n" +
         "Commit: " + webhook.commit.title + "\n" +
         "Author: " + webhook.user.name + "\n" +
         "Duration: " + string(webhook.object_attributes.duration) + "s"

severity: webhook.object_attributes.status == "failed" ? "critical" :
          webhook.object_attributes.status == "canceled" ? "medium" : "info"

source: "gitlab"
link: webhook.project.web_url + "/-/pipelines/" + string(webhook.object_attributes.id)

filter: webhook.object_attributes.status in ["failed", "canceled"]
```

{% endtab %}

{% tab title="Deployment event" %}

```cel
title: "Deployment " + webhook.status + " to " + webhook.environment + ": " + webhook.project.path_with_namespace
message: "Deployment to " + webhook.environment + " " + webhook.status + "\n\n" +
         "Commit: " + webhook.commit_title + "\n" +
         "SHA: " + webhook.short_sha + "\n" +
         "User: " + webhook.user.name

severity: webhook.status == "failed" ? "critical" :
          webhook.status == "canceled" ? "medium" : "info"

source: "gitlab"
link: webhook.deployable_url

filter: webhook.status in ["failed", "canceled"] && webhook.environment == "production"
```

{% endtab %}

{% tab title="Release event" %}

```cel
title: "Release " + webhook.tag + ": " + webhook.project.path_with_namespace
message: "New release published: " + webhook.name + "\n\n" + webhook.description
severity: "info"
source: "gitlab"
link: webhook.url
filter: webhook.action == "create"
```

{% endtab %}
{% endtabs %}

***

### Available GitLab webhook headers <a href="#available-gitlab-webhook-headers" id="available-gitlab-webhook-headers"></a>

| Header              | Description                                              | Example                                            |
| ------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| `X-Gitlab-Event`    | Event type                                               | `Pipeline Hook`, `Deployment Hook`, `Release Hook` |
| `X-Gitlab-Token`    | Secret token, sent as plain text (if configured)         | (if configured)                                    |
| `X-Gitlab-Instance` | GitLab instance URL                                      | `https://gitlab.com`                               |
| `webhook-signature` | HMAC-SHA256 signature (if a signing token is configured) | `v1,<base64_signature>`                            |
| `webhook-id`        | Unique message ID used in signature computation          | `msg_2wF...`                                       |
| `webhook-timestamp` | Unix timestamp used in signature computation             | `1717000000`                                       |

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* [Route alerts](/ai-sre/ai-sre-for-administrators/set-up-alert-management/alert-rules/overview.md): Route GitLab events.
* [Use CEL in webhooks](/ai-sre/ai-sre-for-administrators/set-up-alert-management/webhooks/use-cel-webhooks.md): Add advanced filtering.
* [GitLab template](/ai-sre/ai-sre-for-administrators/set-up-alert-management/webhooks/templates/cicd/gitlab.md): Use the pre-configured template.

***

### Related documentation <a href="#related-documentation" id="related-documentation"></a>

#### GitLab official documentation <a href="#gitlab-official-documentation" id="gitlab-official-documentation"></a>

* [Webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html): Complete guide to GitLab webhook configuration and setup.
* [Webhook events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html): Event-specific payload structures (pipeline, deployment, release).
* [Pipeline events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#pipeline-events): Pipeline webhook payload structure and build details.
* [Deployment events](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#deployment-events): Deployment webhook payload and environment information.