Event

trigger.gitlab_event

TriggerBusiness appsconnection requiredruns in-engine

Creates a project webhook on the tenant's GitLab instance at publish and starts one run per delivery, checked against the token GitLab echoes back.

Start a run when a GitLab project event arrives (push, merge request, issue, comment, pipeline…).

Ask about GitLab All GitLab nodes Provider API docs ↗

Connection

Required: Yes — the node will not save without one
Auth type: API key
Providers: GitLab
Secret shape: {"token": "glpat-…"} — a personal or project access token
Config it needs: base_url
Resolved by: config.connection_id, else node.connection_id
Note: The token's user needs the Maintainer or Owner role on the project; GitLab answers 404 (not 403) for a project whose hooks it may not administer, so a 'project not found' at publish usually means the role, not the path. The connection's base_url is the instance — set it for self-hosted GitLab; blank means gitlab.com. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to a URL the instance can reach, which for a private instance means reachable from inside its network.

Configuration

3 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
project Which project to watch: its numeric id, or its full path (group/project, group/subgroup/project).	string	Yes	—	1–255 characters	acme/app
events Which GitLab events fire a run. Each one is a boolean on the webhook, so this is a closed list — GitLab has no free-text event names.	array	No	["push"]	1–15 characters; array of string	—
branch_filter Only fire push events for branches matching this wildcard pattern, e.g. 'main' or 'release-*'. Ignored by every other event. Blank matches every branch.	string	No	—	≤ 255 characters	main

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "branch_filter": "main",
  "events": [
    "push"
  ],
  "project": "acme/app"
}

Output

One shape.

gitlab event

The flattened GitLab event. `payload` keys depend on object_kind, so the shape is open below the declared fields.

Extra keys beyond the ones listed can appear.

Field	Type	Example
event GitLab's X-Gitlab-Event header — 'Push Hook', 'Merge Request Hook', 'Note Hook'… Branch on this when the trigger subscribes to more than one.	string	Merge Request Hook
object_kind The payload's own name for the resource: push, tag_push, issue, note, merge_request, pipeline, build (a job), wiki_page, deployment, release.	string	merge_request
event_type A finer split than object_kind on newer GitLab payloads (an Issue Hook for a work item says work_item). Empty where GitLab does not send it.	string	—
action What happened to the object — open, close, reopen, update, merge, approved. Empty on events with no object_attributes block, such as push.	string	open
project.id The project's numeric id.	number	42
project.path_with_namespace group/project, as GitLab writes it.	string	acme/app
project.web_url The project's page.	string	—
user.username Who caused the event. Lifted from either shape GitLab uses — the nested user object, or the top-level user_username a push carries.	string	octo
user.name That user's display name.	string	Octo Cat
user.id That user's numeric id.	number	7
delivery_id GitLab's id for this delivery (the webhook-id header, else X-Gitlab-Event-UUID). Also the idempotency key: a retry carries the same value, so it joins the run it already started instead of starting a second.	string	8c4f9b2e-2f1a-4c0e-9a33-6f1b0a2c7d55
payload GitLab's body exactly as sent — commits, object_attributes, changes, repository — for everything the fields above do not lift out.	object	—

{
  "action": "open",
  "delivery_id": "8c4f9b2e-2f1a-4c0e-9a33-6f1b0a2c7d55",
  "event": "Merge Request Hook",
  "event_type": "merge_request",
  "object_kind": "merge_request",
  "payload": {
    "object_kind": "merge_request"
  },
  "project": {
    "id": 42,
    "path_with_namespace": "acme/app",
    "web_url": "https://gitlab.com/acme/app"
  },
  "user": {
    "id": 7,
    "name": "Octo Cat",
    "username": "octo"
  }
}

Notes

Publishing creates the webhook on the project; unpublishing, disabling or archiving deletes it. A workflow that is off is off at GitLab too.
Re-publishing reuses the hook already pointing at this workflow's callback and deletes any duplicate at the same URL, so a half-finished publish heals instead of doubling every run.
Deliveries are checked against the X-Gitlab-Token GitLab echoes back. That is a shared secret in a header, not a signature over the body: it proves who sent the request, not that the body is unmodified in transit.
One run per delivery, idempotent on GitLab's own delivery id — a retry cannot start a second run.
GitLab disables a webhook itself after four consecutive failures (and permanently after 40). Publish again to re-enable it.

Related GitLab nodes

Solutions with GitLab

See Event run in a workflow.

In a technical demo we add the GitLab connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales