GitLab
Start agents from issues, merge requests and comments in a GitLab project, and post their results as comments.
On this page
| Modes | Inbound, outbound |
| YAML type | gitlab |
| Credentials | A Connection of type gitlab, with the instance's base URL and an access token |
| Bridge | Not supported. The GitLab instance must be reachable from the internet. |
| Custom domain | Not supported |
| Linked agents | One or more. A matching event starts every linked agent. |
| While paused | Events get 200 and start no runs. Outbound sends nothing. |
Set up
In GitLab, create an access token with the
apiscope: a project access token under the project's Settings → Access tokens, a group access token, or a personal access token. For inbound connectors, give it the Maintainer role, since connic adds a webhook to the project. Connectors act as the token's user; see Token and user.In connic, open Project Settings → Connections, click New connection, and choose GitLab. You can also create the Connection from the Connection picker in the connector form. Enter a Name, keep Base URL at
https://gitlab.comor enter your self-managed instance, paste the token under Access token, and click Create connection. connic checks the token with GitLab.Open the agent. In Connector Flow, click Add inbound connector for project events or Add outbound connector for replies. Then click Create New Connector and choose GitLab.
Choose the mode, Inbound (Project events) or Outbound (Replies), and pick the Connection under Connection. For inbound, enter the Project by its path, such as
acme/api, and the Events. Click Create. An inbound connector adds its webhook to the project now. For outbound, then choose how the agent uses the connector and click Link connector.
Configuration
The fields of a GitLab connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | gitlab. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Inbound and outbound. Name or ID of a GitLab Connection. Dashboard: Connection. |
| config | object | Optional | GitLab settings. Inbound only; an outbound connector needs none. |
| project | string | Required | Inbound. The project's path, such as acme/api, or its numeric ID. The connector receives its events. Dashboard: Project. |
| events | string[] | Required | Inbound. The events that start runs. Each entry is issues, merge_requests, or notes (comments), or one of them with an action to trigger on that action only: open, close, reopen, and update for issues and merge requests, also merge, approved, unapproved, approval, and unapproval for merge requests, and create and update for comments, such as merge_requests.merge. Dashboard: Events, one per line, starting with issues.open and notes.create. |
The base URL and the access token belong to the Connection, not to the connector.
Generated values
connic sets these when you save the connector or its Connection.
| Value | Modes | Description |
|---|---|---|
| Webhook | Inbound | The connector's webhook in the GitLab project, with a secret token and a signing token connic generates. connic adds it when you save the connector, so you don't create it in GitLab. |
| Project ID | Inbound | GitLab's numeric ID of the project you enter by its path, so renaming the project doesn't break the connector. |
| User | Inbound, outbound | The ID and username of the token's user, stored on the Connection when you save it. |
Agent input
Modes: Inbound
An inbound connector starts a run for every linked agent each time an event in its project matches its events. The run receives:
{
"event": "notes",
"action": "create",
"project": "acme/api",
"type": "merge_request",
"iid": 42,
"conversation_id": "gitlab:gitlab.com/1234!42",
"title": "Round EUR totals once",
"text": "Still one cent off after the last push.",
"url": "https://gitlab.com/acme/api/-/merge_requests/42#note_9876",
"author": "jane",
"raw": { ... }
}eventandactionare the event as you list it inevents, and GitLab's action, such asopenorcreate.typeisissueormerge_request, also for comments, andiidits number in the project.titleis its title.conversation_idstays the same for every event of one issue or merge request. To give the agent the earlier comments as history, setsession.key: input.conversation_idin its YAML; the connector doesn't turn on sessions by itself.textis the description or the comment, in Markdown, andurlthe link to it.authoris the username of the person who caused the event.rawis GitLab's full webhook payload as sent.
Comments on commits and snippets, confidential issues, and their comments start no runs. An event that GitLab delivers again doesn't start another run. Inbound mode doesn't reply by itself: to comment on the issue or merge request, link the agent to an outbound GitLab connector that uses the same Connection; see Outbound delivery.
Token and user
Connectors act as the token's user. Comments from your agents show that user as their author, and events that user causes are ignored, so agents don't trigger themselves on their own comments. If the token belongs to a person, that person's own changes start no runs either. A project or group access token avoids that, since GitLab gives it a user of its own.
Adding webhooks to a project needs the Maintainer role, so an inbound connector needs a token with it. GitLab access tokens expire; replace the token on the Connection before then. A new project or group access token comes with a new user, which connic reads when you save the Connection.
GitLab webhook
Modes: Inbound
Saving an inbound connector adds a webhook to its project in GitLab for issues, merge requests, comments, or all of them, as its events need. Each connector has its own webhook, so several connectors can watch the same project, for example one per environment. You find the webhooks in GitLab under the project's Settings → Webhooks.
connic checks the secret token of every delivery, and from GitLab 19.0 on also its signature. Changing the connector's events updates its webhook. Changing the project, or the Connection to another GitLab instance, adds a new webhook and removes the old one. Deleting the connector removes its webhook.
Outbound delivery
Modes: Outbound
An outbound GitLab connector posts once each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. It comments on the issue or merge request the run started from, when the run came in through a GitLab inbound connector on the same Connection. Runs that started anywhere else have nothing to reply to, and their delivery fails.
Automatic output
An automatic link posts the run's final output. Plain text becomes the comment. A JSON object takes it from body, text, message, response, or output, in that order. GitLab renders it as Markdown.
{
"body": "The total is rounded in the cart and again at payment. Dropping the second rounding fixes it."
}Agent-tool and middleware payload
The model or middleware passes body, which is required and can't be empty. Other fields are rejected.
{
"body": "Reproduced on main: the total is rounded twice."
}Delivery and retries
When GitLab rate-limits a comment or can't be reached, connic waits and sends it again. When GitLab's answer gets lost, connic doesn't resend, since the comment may already exist. The connector's runs show each delivery with the comment's ID, or with the error.
Limits and errors
| Limit | Value |
|---|---|
| GitLab version | 17.4 or later. GitLab signs deliveries from 19.0 on. |
| Answer to GitLab | connic answers right away and runs the agents afterwards. |
| Failing webhook | GitLab turns a webhook off for a while after 4 failed deliveries in a row, starting at one minute and growing up to 24 hours, and for good after 40. To turn it back on, send a test request from the webhook's settings in GitLab. |
| New webhooks | GitLab adds at most five webhooks per minute for one user in one project. Saving more connectors for the same project at once can fail; save again a minute later. |
| Comment length | 1,000,000 characters. |
Requests with a missing or wrong secret token or signature get 401. Saving a Connection fails when the base URL isn't HTTPS or GitLab rejects the token. Saving an inbound connector fails when the token's user can't see the project or lacks the Maintainer role. A delivery fails when GitLab rejects the comment, for example when the issue was deleted.