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,...

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

References

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

Configuration

Setting Up cdviz-collector

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-pro repository
[remote.transformers-pro]
type = "github"
owner = "cdviz-dev"
repo = "transformers-pro"
# token = "xxx"  # set by env 'CDVIZ_COLLECTOR__REMOTE__TRANSFORMERS-PRO'

[transformers]
gitlab_events = { type = "vrl", template_rfile = "transformers-pro:///gitlab_events/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-pro repository. For more details on remote transformers, see the Transformers documentation.

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://demo.cdviz.dev/webhook/000-gitlab -H 'X-Gitlab-Token: xxxxxxx'

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

Setting Up GitLab Webhook

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-gitlab
4. Secret token: Enter the token from your collector configuration (the same as value for header x-gitlab-token defined in the configuration)
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

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.