GitLab Integration
Connect GitLab to Koalr for merge request analytics, pipeline data, DORA metrics, and deploy risk scoring — supports GitLab.com and self-hosted instances.
Overview
The GitLab integration brings merge request (MR) data, pipeline events, and push activity into Koalr — giving you the same DORA metrics, PR analytics, flow metrics, and deploy risk scoring available to GitHub-connected teams.
Koalr ingests GitLab data via a system-hook webhook. When an MR is opened, updated, or merged; when a pipeline runs; or when commits are pushed, GitLab sends a signed event to Koalr's webhook receiver. Koalr verifies the signature, resolves the organization, and enqueues the event for processing — typically within seconds.
Both GitLab.com (SaaS) and self-hosted GitLab instances (CE and EE) are supported.
What Koalr syncs
| Data | Sync method | Frequency |
|---|---|---|
| Merge requests (open, merged) | Webhook | Real-time |
| MR reviews and approvals | Webhook | Real-time |
| Pipeline runs and outcomes | Webhook | Real-time |
| Push events (commits) | Webhook | Real-time |
| Repository metadata | REST backfill | On connect |
| CI/CD status per MR | Webhook | Real-time |
Backfill on connect: After the webhook is configured, Koalr triggers a one-time REST backfill of the last 90 days of MR and pipeline history so your dashboards populate immediately.
Connecting GitLab
GitLab.com
- In Koalr, go to Settings → Integrations.
- Click Connect next to GitLab.
- Copy the webhook URL and secret token displayed in the dialog.
- In GitLab, go to Admin Area → System Hooks (requires GitLab group Owner or Admin).
- Paste the webhook URL into the URL field.
- Paste the secret token into the Secret token field.
- Enable the following trigger checkboxes:
- Merge request events
- Pipeline events
- Push events
- Leave SSL verification enabled (recommended) and click Add system hook.
- Return to Koalr and click Verify connection.
Koalr sends a test ping and confirms the webhook is receiving events before marking the integration as active.
Self-hosted GitLab
The setup is identical, with one additional step: your GitLab instance must be able to reach Koalr's webhook endpoint over the internet.
Webhook URL for self-hosted: https://api.koalr.com/integrations/gitlab/webhook
If your GitLab instance is behind a corporate firewall or private network, configure an egress rule to allow outbound HTTPS requests to api.koalr.com on port 443.
If your self-hosted instance uses a private CA certificate, disable SSL verification in the system hook settings — or add Koalr's public certificate to your GitLab instance's trusted CA store.
Required permissions
| Role | Where required |
|---|---|
| GitLab Admin | Required to create System Hooks |
| Group Owner (fallback) | For group-level webhooks (EE only) |
GitLab EE note: If you do not have instance-level Admin access, GitLab EE supports group-level webhooks (under Group → Settings → Webhooks) that cover all projects within the group. Use the same URL and token. Group webhooks support merge request and pipeline events but not push events at the group level — push events require individual project webhooks in that case.
Webhook security
Koalr verifies every inbound webhook request using the secret token you provided during setup. The verification uses SHA-256 HMAC with constant-time comparison against the X-Gitlab-Token header — preventing timing attacks. Requests with a missing or invalid token are rejected with a 401 Unauthorized response and never enqueued.
Keep your secret token confidential. If it is ever compromised, disconnect and reconnect the integration from Settings → Integrations → GitLab to rotate to a new token.
Feature availability vs. GitHub
Most Koalr features are fully supported with GitLab. A small number of GitHub-specific features depend on GitHub-native APIs and are not available.
| Feature | GitLab | GitHub |
|---|---|---|
| PR / MR analytics | Yes | Yes |
| DORA metrics (all 4) | Yes | Yes |
| Deploy risk scoring | Yes | Yes |
| Pipeline / CI status | Yes | Yes |
| Review queue | Yes | Yes |
| Flow metrics | Yes | Yes |
| Cycle time | Yes | Yes |
| CODEOWNERS sync | No | Yes |
| GitHub Copilot analytics | No | Yes |
| GitHub Check Run (deploy risk gate) | No | Yes |
| Deployments API (native) | No | Yes |
CODEOWNERS: GitLab supports CODEOWNERS files, but Koalr's CODEOWNERS sync currently uses the GitHub API. GitLab CODEOWNERS sync is on the roadmap. In the meantime, you can use Custom Metrics to track ownership manually.
Deploy risk gate: On GitHub, Koalr posts a Check Run that can block merges. On GitLab, deploy risk scores are visible in the Koalr dashboard and via the VS Code extension — MR-level gating via GitLab External Status Checks is planned.
Merge request data mapped to Koalr metrics
| GitLab MR field | Koalr metric |
|---|---|
created_at | PR open time (cycle time start) |
merged_at | Merge time (cycle time end, DORA lead) |
first_commit_at | First commit time (coding time start) |
review_time | Time in review |
changes_count | PR size (lines changed) |
Pipeline status | CI status, change failure rate |
Pipeline duration | Build duration trend |
Troubleshooting
Events not appearing after webhook setup
Check that the system hook is listed as active in GitLab Admin → System Hooks. Click Test next to the hook and verify GitLab reports a 200 response. If it shows a connection error, confirm api.koalr.com is reachable from your GitLab instance.
"Unauthorized" on test ping
The secret token in GitLab must exactly match the token shown in Koalr's integration dialog (no leading or trailing whitespace). Disconnect and reconnect the integration to generate a fresh token if needed.
MR data missing after backfill
Backfill covers the most recent 90 days of merged MRs and pipeline runs. Data older than 90 days is not backfilled. If your dashboards show less history than expected, confirm that the webhook has been active long enough to capture ongoing activity.
Self-hosted: SSL handshake errors
If your GitLab instance uses a self-signed certificate for its own HTTPS, this does not affect Koalr's webhook receiver (which uses a publicly trusted cert). The SSL verification setting in the system hook controls whether GitLab verifies Koalr's certificate when delivering events. Leave SSL verification enabled unless you are testing on a non-production Koalr endpoint.
Duplicate events
GitLab retries webhook delivery if it does not receive a 200 response within 10 seconds. Koalr's webhook receiver is idempotent — duplicate deliveries of the same event are deduplicated by event ID before processing.