GitLab WebHook Integration

Collect GitLab events (via webhooks), transform them to cdevents.

• GitLab tracks all changes to repositories, issues, merge requests, releases, pipelines, jobs, and more. And it notifies a webhook about these changes.
• cdviz-collector transforms these events to cdevents, and sends them to the database, listeners,...

From event	CDEvents
release.created	artifact.published
tag_push	artifact.published
push (branch)	branch.{created, deleted}
merge_request.open/reopen	change.created
merge_request.merge	change.merged
merge_request.close	change.abandoned
merge_request.approved	change.reviewed
merge_request.update	change.updated
pipeline.created/pending	pipelineRun.queued
pipeline.running	pipelineRun.started
pipeline.success/failed	pipelineRun.finished
build.running	taskRun.started
build.success/failed	taskRun.finished
issue.open/reopen	ticket.created
issue.close	ticket.closed
issue.update	ticket.updated

References

• Source code of the transformer
• GitLab Webhooks and Events
• Examples of cdevents converted from GitLab's events

Configuration

CDviz Side

Configure cdviz-collector.toml to receive GitLab webhook events:

[sources.gitlab_webhook]
enabled = true
transformer_refs = ["gitlab_events"]

[sources.gitlab_webhook.extractor]
type = "webhook"
id = "000-gitlab" # used as part of the webhook's url
headers_to_keep = ["X-Gitlab-Event"]

[sources.gitlab_webhook.extractor.headers]
# value set by env CDVIZ_COLLECTOR__SOURCES__GITLAB_WEBHOOK__EXTRACTOR__HEADERS__X-GITLAB-TOKEN__VALUE
"x-gitlab-token" = { type = "equals", value = "xxx", case_sensitive = true }

# Transformer from transformers-community repository
[remote.transformers-community]
type = "github://cdviz-dev/transformers-community"
# token = "xxx"  # set by env 'CDVIZ_COLLECTOR__REMOTE__TRANSFORMERS-COMMUNITY'

[transformers]
gitlab_events = { type = "vrl", template_rfile = "transformers-community:///gitlab_webhook/transformer.vrl" }

Replace "token-changeme" with your actual secret token configured in GitLab webhook settings.

The template_rfile references the VRL transformation logic from the transformers-community repository. For more details on remote transformers, see the Transformers documentation.

The webhook endpoint to declare on GitLab's side is then http://your-collector-url/webhook/000-gitlab.

Nothing to run, and no transformer to configure: the endpoint is provisioned for your tenant.

1. Open app.cdviz.dev → Settings → Collector.
2. Enable GitLab Webhook.
3. Copy the Endpoint — https://app.cdviz.dev/collect/<your-tenant>/webhook/gitlab.
4. Reveal (or regenerate) the token sent as the x-gitlab-token header. You are free to change it, as long as GitLab and CDviz hold the same value.

Testing the access to the webhook

Make an empty POST to the endpoint, it should be rejected with HTTP status 400.

❯ curl -i -X POST https://your-collector-url/webhook/000-gitlab -H 'X-Gitlab-Token: xxxxxxx'

HTTP/2 400
...
Failed to parse the request body as JSON

❯ curl -i -X POST https://app.cdviz.dev/collect/your-tenant/webhook/gitlab -H 'X-Gitlab-Token: xxxxxxx'

HTTP/2 400
...
Failed to parse the request body as JSON

GitLab Side

Configure a webhook in your GitLab project or group:

1. Navigate to Settings > Webhooks
   • For projects: https://gitlab.com/<namespace>/<project>/-/hooks
   • For groups: https://gitlab.com/groups/<group>/-/hooks
2. Click Add new webhook
3. URL: http://your-collector-url/webhook/000-gitlabthe endpoint copied above, https://app.cdviz.dev/collect/<your-tenant>/webhook/gitlab
4. Secret token: Enter the token from the CDviz Side section above (the value of the x-gitlab-token header)
5. Select Trigger events:
   • ✅ Push events
   • ✅ Tag push events
   • ✅ Issues events
   • ✅ Confidential issues events
   • ✅ Merge request events
   • ✅ Job events
   • ✅ Pipeline events
   • ✅ Deployment events
   • ✅ Release events
   • ✅ Vulnerability events
6. Enable SSL verification (recommended for production)
7. Ensure Enable webhook is checked
8. Click Add webhook

Testing the Integration

Test webhook delivery: use the Test button

Check webhook delivery logs in GitLab: Settings > Webhooks > Edit > Recent events

Self-hosted only

To verify webhook reception before transformation:

[sources.gitlab_webhook]
transformer_refs = ["log", "discard_all"]  # Log payloads without processing

For webhook troubleshooting, see the Webhook Extractor documentation.

Event Mapping

The transformer converts GitLab webhook events into CDEvents following the CDEvents specification:

GitLab Event	CDEvent Type	Detection Logic
pipeline:created/pending	pipelineRun.queued	object_kind=pipeline AND status in [created, waiting_for_resource, preparing, pending]
pipeline:running	pipelineRun.started	object_kind=pipeline AND status=running
pipeline:success/failed	pipelineRun.finished	object_kind=pipeline AND status in [success, failed, canceled, skipped]
build:running	taskRun.started	object_kind=build AND build_status=running
build:success/failed	taskRun.finished	object_kind=build AND build_status in [success, failed, canceled]
release:created	artifact.published	object_kind=release
tag_push	artifact.published	object_kind=tag_push AND tag created
issue:open/reopen	ticket.created	object_kind=issue AND action in [open, reopen]
issue:close	ticket.closed	object_kind=issue AND action=close
issue:update	ticket.updated	object_kind=issue AND other actions
merge_request:open/reopen	change.created	object_kind=merge_request AND action in [open, reopen]
merge_request:merge	change.merged	object_kind=merge_request AND action=merge
merge_request:close	change.abandoned	object_kind=merge_request AND action=close (not merged)
merge_request:approved	change.reviewed	object_kind=merge_request AND action=approved
merge_request:update	change.updated	object_kind=merge_request AND other actions
push (branch)	branch.created/deleted	object_kind=push AND ref starts with refs/heads/

CDEvent Structure

The VRL transformation generates CDEvents with:

• context.id: Auto-generated by collector
• context.source: Automatically set to {http.root_url}/?source={source_name} where {source_name} is the configuration key (e.g., gitlab_webhook)
• subject.id: Web URL of the entity (pipeline, job, issue, MR) or PURL for artifacts
• subject.source: Empty (not set)
• customData.gitlab: Selected GitLab-specific metadata (project, user, event-specific details)

Artifact Identification

For artifact.published events, the subject.id is a PURL (Package URL):

• Release: pkg:generic/<project_path>@<tag_name>?repository_url=<encoded_url>
• Tag Push: pkg:generic/<project_path>@<tag_name>?repository_url=<encoded_url>

Event Coverage

Supported Events:

• ✅ Pipeline lifecycle (queued, started, finished)
• ✅ Job lifecycle (started, finished)
• ✅ Issues (created, updated, closed)
• ✅ Merge requests (created, updated, merged, abandoned, reviewed)
• ✅ Releases and tags (artifact published)
• ✅ Branch operations (created, deleted)

Not Yet Supported:

• Deployment events → service.deployed
• Wiki page events
• Comment events
• Confidential issues/MRs
• System hooks

These can be added following the existing pattern in the transformer VRL file.