<!-- BusyBot node reference — https://busybot.net/tools/gitlab-trigger/ -->

> Node: GitLab Trigger (`gitlab_trigger`) · Webhook trigger · v1
> Category: Development · Credentials: GitLab API (`gitlabApi`)
> Updated: 2026-08-16

# GitLab Trigger

> Trigger workflows from GitLab repository events

## Overview

Triggers a workflow when events happen in a GitLab repository, such as pushes, merge requests, issues, pipeline status changes, comments, deployments, releases, tags, wiki page changes, and more. Receives webhook POST requests from GitLab and normalizes the payload for downstream processing.

**Category:** Development  
**Tool Name:** `gitlab_trigger`  
**Version:** 1

**Appearance:** Icon: `si-gitlab` | Color: `#fc6d26`

## Node Type

**Trigger** — webhook (receives incoming HTTP callbacks)

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | None (trigger node) |
| Output | `Output` |

## Credentials

This tool requires **GitLab API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/gitlab-api/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Repository Owner | `string` | Yes | — | User, group, or namespace that owns the repository. For subgroups, use the full path (e.g., group/subgroup). |
| Repository Name | `string` | Yes | — | The name of the GitLab project/repository. |
| Events | `multiOptions` | Yes | `[]` | The events to listen to. Select * to subscribe to all event types. |
| | | | | Options: `note` (a comment on a commit, merge request, issue or snippet), `confidential_note`, `confidential_issues`, `deployment`, `issues`, `job` (a job status change), `merge_requests`, `pipeline` (a pipeline status change), `push` (excludes tag pushes), `releases`, `tag_push` (a tag was created or deleted), `wiki_page`, `*` (All Events — any time any event is triggered) |

## Output Data

Each accepted delivery produces one output item describing the GitLab event:

```json
{
  "body": {},
  "headers": {},
  "query": {},
  "_trigger": "gitlab_webhook",
  "_timestamp": "2026-01-01T00:00:00.000Z",
  "_webhookEvent": "Push Hook"
}
```

- `body` — the GitLab event payload exactly as GitLab sent it (for example `object_kind`, `event_name`, `ref`, `project`, `commits`, `repository`).
- `headers` — the request headers of the delivery.
- `query` — the query-string parameters of the delivery.
- `_trigger` — always `gitlab_webhook`.
- `_timestamp` — ISO 8601 timestamp of when the delivery arrived.
- `_webhookEvent` — the GitLab hook name taken from the `X-Gitlab-Event` header, such as `Push Hook`, `Merge Request Hook`, `Issue Hook`, `Pipeline Hook`, `Note Hook`, `Tag Push Hook`, `Job Hook`, `Deployment Hook`, `Release Hook` or `Wiki Page Hook`.

Reference the payload downstream by expression, for example `{{ $json.body.project.path_with_namespace }}` or `{{ $json.body.object_attributes.state }}`.

Deliveries for hook types you did not select are acknowledged with `200` but do not start the workflow, so GitLab does not retry them. Deliveries whose secret token does not match are rejected with `401`.

## Usage Examples

- Start a CI/CD workflow when code is pushed to a GitLab repository
- Notify a Slack channel when a merge request is opened or merged
- Track issue creation and updates in GitLab projects
- Monitor pipeline status changes for deployment automation
- Trigger a build when a new tag is pushed to GitLab

## Example Configuration

Start a build on every push to a project:

```json
{
  "type": "gitlab_trigger",
  "parameters": {
    "owner": "my-group",
    "repository": "my-project",
    "events": ["push"]
  }
}
```

Watch merge requests and issues in a subgroup project:

```json
{
  "type": "gitlab_trigger",
  "parameters": {
    "owner": "my-group/platform",
    "repository": "api-service",
    "events": ["merge_requests", "issues", "note"]
  }
}
```

React to pipeline and job status changes:

```json
{
  "type": "gitlab_trigger",
  "parameters": {
    "owner": "my-group",
    "repository": "my-project",
    "events": ["pipeline", "job", "deployment"]
  }
}
```

Subscribe to every GitLab event type:

```json
{
  "type": "gitlab_trigger",
  "parameters": {
    "owner": "my-group",
    "repository": "my-project",
    "events": ["*"]
  }
}
```

### Trigger Behavior

- **Activation:** When the workflow is activated, a webhook endpoint is registered with the service.
- **Deactivation:** The webhook is automatically unregistered when the workflow is deactivated.
- **Payload:** The incoming webhook payload is parsed and output as workflow items.
- **Verification:** Supports signature verification where applicable.

## Tips

Configure the GitLab Trigger by providing your repository owner and name, then select which events to listen for. When activated, a webhook is registered in your GitLab project. Incoming events are forwarded to your workflow for processing.