GitLab

The GitLab adapter accepts GitLab.com and self-managed GitLab webhook JSON. It can normalize pipeline/build/job, merge request, deployment, issue, incident, and alert events for one OpsKnight service.

Before you begin

You need permission to manage the OpsKnight service and the GitLab project webhook. Decide which GitLab events should reach the service; the adapter does not filter refs or environments after receipt.

Create a GitLab integration under Services → select a service → Integrations. Copy its integration ID and key.

Configure the webhook

In GitLab project → Settings → Webhooks, add:

https://ops.example.com/api/integrations/gitlab?integrationId=INTEGRATION_ID&integrationKey=INTEGRATION_KEY

The query key is supported for senders that cannot add an authentication header, but the complete URL is a secret and can appear in logs. If your GitLab version supports custom webhook headers, prefer X-Integration-Key: INTEGRATION_KEY and omit integrationKey from the URL.

Select only the GitLab trigger types you intend to process, such as pipeline, job, merge request, deployment, and issue events. Keep SSL verification enabled.

Optional GitLab secret token

The integration key and GitLab secret token protect different boundaries:

• the integration key is always required and authorizes/routes the webhook to a service;
• the integration's signature secret, when configured, must also be entered in GitLab's Secret token field; GitLab sends it as X-Gitlab-Token.

If a signature secret exists, OpsKnight rejects a missing or different X-Gitlab-Token. Do not put the integration key in the GitLab Secret token field unless it is deliberately also the configured signature secret.

Event mapping

Pipelines, builds, and jobs

When the payload contains object_attributes.id or build_id, the key is:

gitlab-PROJECT-pipeline-PIPELINE_OR_BUILD_ID

A later status update resolves the incident only if it carries the same ID. A successful new pipeline normally has a different ID and therefore does not resolve an earlier failed pipeline. When no pipeline/build ID is present, the fallback key uses project plus ref, so a later event with that same fallback key can resolve the active incident.

Other supported GitLab events

The adapter records useful GitLab fields plus the raw payload in custom details. Service urgency rules ultimately determine incident urgency; the adapter's normalized severity alone does not guarantee a particular paging outcome.

Test the lifecycle

Use GitLab's webhook test/delivery view first. For a direct connectivity test, keep one synthetic pipeline ID in both requests:

export OPSKNIGHT_URL="https://ops.example.com"
export INTEGRATION_ID="replace-me"
export INTEGRATION_KEY="replace-me"

curl --fail-with-body \
  --request POST \
  "${OPSKNIGHT_URL}/api/integrations/gitlab?integrationId=${INTEGRATION_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Integration-Key: ${INTEGRATION_KEY}" \
  --data '{
    "object_kind": "pipeline",
    "project": { "path_with_namespace": "example/payments" },
    "object_attributes": { "id": 42001, "status": "failed" },
    "ref": "main",
    "sha": "0000000000000000000000000000000000000000"
  }'

Change only status to success and send the same payload again. Confirm the first request creates/updates the intended service incident and the second resolves that same incident. If a signature secret is configured, also send X-Gitlab-Token: SIGNATURE_SECRET.

Accepted requests normally return HTTP 202. Use a unique synthetic ID when repeating this test later so an old resolved incident is not mistaken for the current result.

Troubleshooting

Related topics

• Inbound webhook reference
• How integrations work
• API rate limiting
• Troubleshooting