GitLab
Agenten mit Issues, Merge Requests und Kommentaren in einem GitLab-Projekt starten und ihre Ergebnisse als Kommentar posten.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | gitlab |
| Zugangsdaten | Ein Kontozugang (Connection) vom Typ gitlab mit der Basis-URL der Instanz und einem Access Token |
| Bridge | Nicht unterstützt. Die GitLab-Instanz muss aus dem Internet erreichbar sein. |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jedes passende Event startet alle verknüpften Agenten. |
| Während der Pause | Events erhalten 200 und starten keine Runs. Outbound sendet nichts. |
Einrichtung
Erstelle in GitLab einen Access Token mit dem Scope
api: einen Project Access Token in den Settings → Access tokens des Projekts, einen Group Access Token oder einen Personal Access Token. Für Inbound-Verbindungen gibst du ihm die Rolle Maintainer, weil connic dem Projekt einen Webhook hinzufügt. Verbindungen handeln als der Nutzer, dem der Token gehört; siehe Token und Nutzer.Klicke in connic unter Projekt-Settings → Connections auf New connection und wähle GitLab. Den Kontozugang kannst du auch im Formular der Verbindung über die Auswahl unter Connection anlegen. Gib einen Name ein, lass unter Base URL
https://gitlab.comstehen oder trag deine eigene Instanz ein, füge den Token unter Access token ein und klicke auf Create connection. connic prüft den Token bei GitLab.Öffne den Agenten. Klicke im Connector Flow für Events aus dem Projekt auf Add inbound connector oder für Antworten auf Add outbound connector. Klicke dann auf Create New Connector und wähle GitLab.
Wähle den Modus, Inbound (Project events) oder Outbound (Replies), und unter Connection den Kontozugang. Trag bei Inbound unter Project den Pfad des Projekts ein, etwa
acme/api, und die Events. Klicke auf Create. Eine Inbound-Verbindung fügt dabei ihren Webhook zum Projekt hinzu. Bei Outbound legst du danach fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.
Konfiguration
Die Felder einer GitLab-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Required | gitlab. |
| mode | string | Required | inbound oder outbound. Dashboard: Mode. |
| connection | string | Required | Inbound und Outbound. Name oder ID eines GitLab-Kontozugangs. Dashboard: Connection. |
| config | object | Optional | Einstellungen der GitLab-Verbindung. Nur bei Inbound; eine Outbound-Verbindung braucht keine. |
| project | string | Required | Inbound. Der Pfad des Projekts, etwa acme/api, oder seine Nummer. Die Verbindung erhält seine Events. Dashboard: Project. |
| events | string[] | Required | Inbound. Die Events, die Runs starten. Jeder Eintrag ist issues, merge_requests oder notes (Kommentare), oder einer davon mit einer Aktion, damit nur diese Aktion auslöst: open, close, reopen und update bei Issues und Merge Requests, bei Merge Requests außerdem merge, approved, unapproved, approval und unapproval, bei Kommentaren create und update, etwa merge_requests.merge. Dashboard: Events, einer pro Zeile, vorbelegt mit issues.open und notes.create. |
Basis-URL und Access Token gehören zum Kontozugang, nicht zur Verbindung.
Erzeugte Werte
connic setzt diese Werte, wenn du die Verbindung oder ihren Kontozugang speicherst.
| Wert | Modi | Beschreibung |
|---|---|---|
| Webhook | Inbound | Der Webhook der Verbindung im GitLab-Projekt, mit einem Secret Token und einem Signing Token, die connic erzeugt. connic legt ihn beim Speichern der Verbindung an, du musst ihn also nicht in GitLab einrichten. |
| Projekt-ID | Inbound | Die Nummer, unter der GitLab das Projekt führt, das du mit seinem Pfad einträgst. Benennst du das Projekt um, läuft die Verbindung weiter. |
| Nutzer | Inbound, Outbound | ID und Nutzername des Nutzers, dem der Token gehört. connic speichert beides beim Speichern des Kontozugangs. |
Agent-Input
Modi: Inbound
Eine Inbound-Verbindung startet einen Run für jeden verknüpften Agenten, sobald in ihrem Projekt ein Event eintritt, das zu ihren Events passt. Der Run erhält:
{
"event": "notes",
"action": "create",
"project": "acme/api",
"type": "merge_request",
"iid": 42,
"conversation_id": "gitlab:gitlab.com/1234!42",
"title": "EUR-Beträge nur einmal runden",
"text": "Nach dem letzten Push immer noch einen Cent daneben.",
"url": "https://gitlab.com/acme/api/-/merge_requests/42#note_9876",
"author": "jane",
"raw": { ... }
}eventist das Event, wie du es untereventseinträgst, undactiondie Aktion aus GitLab, etwaopenodercreate.typeistissueodermerge_request, auch bei Kommentaren, undiiddie Nummer im Projekt.titleist der Titel.conversation_idbleibt für alle Events eines Issues oder Merge Requests gleich. Soll dein Agent die früheren Kommentare als Verlauf kennen, setze in seiner YAMLsession.key: input.conversation_id. Von sich aus schaltet der Connector keine Sessions ein.textist die Beschreibung oder der Kommentar in Markdown undurlder Link dorthin.authorist der Nutzername der Person, die das Event ausgelöst hat.rawenthält den vollständigen Webhook-Payload, so wie GitLab ihn gesendet hat.
Kommentare zu Commits und Snippets, vertrauliche Issues und deren Kommentare starten keine Runs. Stellt GitLab ein Event erneut zu, startet kein weiterer Run. Der Inbound-Modus antwortet nicht von selbst: Für einen Kommentar im Issue oder Merge Request verknüpfst du den Agenten mit einer Outbound-GitLab-Verbindung, die denselben Kontozugang nutzt; siehe Outbound-Zustellung.
Token und Nutzer
Verbindungen handeln als der Nutzer, dem der Token gehört. Kommentare deiner Agenten erscheinen unter diesem Nutzer, und Events, die er auslöst, ignoriert connic. So starten sich Agenten nicht mit ihren eigenen Kommentaren selbst. Gehört der Token einer Person, starten auch deren eigene Änderungen keine Runs. Ein Project oder Group Access Token vermeidet das, weil GitLab ihm einen eigenen Nutzer gibt.
Webhooks dürfen in einem Projekt nur Maintainer hinzufügen, eine Inbound-Verbindung braucht also einen Token mit dieser Rolle. Access Tokens laufen in GitLab ab; ersetze den Token im Kontozugang vorher. Ein neuer Project oder Group Access Token bringt einen neuen Nutzer mit, den connic beim Speichern des Kontozugangs übernimmt.
GitLab-Webhook
Modi: Inbound
Beim Speichern einer Inbound-Verbindung fügt connic ihrem Projekt in GitLab einen Webhook hinzu, je nach ihren Events für Issues, Merge Requests, Kommentare oder alles davon. Jede Verbindung hat ihren eigenen Webhook, mehrere Verbindungen können also dasselbe Projekt beobachten, etwa eine pro Environment. Du findest die Webhooks in GitLab in den Settings → Webhooks des Projekts.
connic prüft bei jeder Zustellung das Secret Token und ab GitLab 19.0 auch die Signatur. Änderst du die Events der Verbindung, aktualisiert connic ihren Webhook. Wechselst du das Projekt oder stellst den Kontozugang auf eine andere GitLab-Instanz um, legt connic einen neuen Webhook an und entfernt den alten. Löschst du die Verbindung, entfernt connic ihren Webhook.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-GitLab-Verbindung postet bei jeder Nutzung einmal: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Kam der Run über eine Inbound-GitLab-Verbindung mit demselben Kontozugang, kommentiert sie das Issue oder den Merge Request, aus dem er stammt. Bei Runs, die anders gestartet wurden, gibt es nichts zu beantworten, und die Zustellung schlägt fehl.
Automatische Ausgabe
Eine automatische Verknüpfung postet die finale Ausgabe des Runs. Klartext wird zum Kommentar. Bei einem JSON-Objekt kommt er aus body, text, message, response oder output, in dieser Reihenfolge. GitLab stellt ihn als Markdown dar.
{
"body": "Der Betrag wird im Warenkorb und noch einmal bei der Zahlung gerundet. Ohne die zweite Rundung stimmt er."
}Payload für Agent-Tool und Middleware
Das Modell oder die Middleware übergibt body, Pflicht und nicht leer. Andere Felder werden abgelehnt.
{
"body": "Auf main nachgestellt: Der Betrag wird doppelt gerundet."
}Zustellung und Wiederholungen
Bremst GitLab einen Kommentar per Rate Limit aus oder ist nicht erreichbar, wartet connic und sendet erneut. Geht die Antwort von GitLab verloren, sendet connic nicht erneut, weil der Kommentar schon existieren kann. Die Runs der Verbindung zeigen jede Zustellung mit der ID des Kommentars oder mit dem Fehler.
Limits und Fehler
| Limit | Wert |
|---|---|
| GitLab-Version | 17.4 oder neuer. Ab 19.0 signiert GitLab die Zustellungen. |
| Antwort an GitLab | connic antwortet sofort und startet die Agenten danach. |
| Fehlschlagender Webhook | Nach 4 fehlgeschlagenen Zustellungen in Folge schaltet GitLab einen Webhook vorübergehend ab, zuerst für eine Minute und dann immer länger bis zu 24 Stunden, nach 40 dauerhaft. Wieder einschalten kannst du ihn mit einer Testanfrage in seinen Einstellungen in GitLab. |
| Neue Webhooks | GitLab legt pro Nutzer und Projekt höchstens fünf Webhooks pro Minute an. Speicherst du mehrere Verbindungen für dasselbe Projekt auf einmal, kann das fehlschlagen; speichere dann eine Minute später erneut. |
| Länge eines Kommentars | 1.000.000 Zeichen. |
Anfragen mit fehlendem oder falschem Secret Token oder falscher Signatur erhalten 401. Ein Kontozugang lässt sich nicht speichern, wenn die Basis-URL kein HTTPS nutzt oder GitLab den Token ablehnt. Eine Inbound-Verbindung lässt sich nicht speichern, wenn der Nutzer des Tokens das Projekt nicht sieht oder nicht Maintainer ist. Eine Zustellung schlägt fehl, wenn GitLab den Kommentar ablehnt, etwa weil das Issue gelöscht wurde.