Skip to main content
connic
Connectors

GitLab

Start agents from issues, merge requests and comments in a GitLab project, and post their results as comments.

Last updated
ModesInbound, outbound
YAML typegitlab
CredentialsA Connection of type gitlab, with the instance's base URL and an access token
BridgeNot supported. The GitLab instance must be reachable from the internet.
Custom domainNot supported
Linked agentsOne or more. A matching event starts every linked agent.
While pausedEvents get 200 and start no runs. Outbound sends nothing.

Set up

  1. In GitLab, create an access token with the api scope: 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.

  2. 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.com or enter your self-managed instance, paste the token under Access token, and click Create connection. connic checks the token with GitLab.

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

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

FieldTypeStatusDescription
typestringRequiredgitlab.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredInbound and outbound. Name or ID of a GitLab Connection. Dashboard: Connection.
configobjectOptionalGitLab settings. Inbound only; an outbound connector needs none.
projectstringRequiredInbound. The project's path, such as acme/api, or its numeric ID. The connector receives its events. Dashboard: Project.
eventsstring[]RequiredInbound. 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.

ValueModesDescription
WebhookInboundThe 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 IDInboundGitLab's numeric ID of the project you enter by its path, so renaming the project doesn't break the connector.
UserInbound, outboundThe 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:

payload.json
{
  "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": { ... }
}
  • event and action are the event as you list it in events, and GitLab's action, such as open or create.
  • type is issue or merge_request, also for comments, and iid its number in the project. title is its title.
  • conversation_id stays the same for every event of one issue or merge request. To give the agent the earlier comments as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • text is the description or the comment, in Markdown, and url the link to it.
  • author is the username of the person who caused the event.
  • raw is 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.

output.json
{
  "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.

connector-payload.json
{
  "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

LimitValue
GitLab version17.4 or later. GitLab signs deliveries from 19.0 on.
Answer to GitLabconnic answers right away and runs the agents afterwards.
Failing webhookGitLab 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 webhooksGitLab 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 length1,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.