Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

GitLab

Agenten mit Issues, Merge Requests und Kommentaren in einem GitLab-Projekt starten und ihre Ergebnisse als Kommentar posten.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typgitlab
ZugangsdatenEin Kontozugang (Connection) vom Typ gitlab mit der Basis-URL der Instanz und einem Access Token
BridgeNicht unterstützt. Die GitLab-Instanz muss aus dem Internet erreichbar sein.
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jedes passende Event startet alle verknüpften Agenten.
Während der PauseEvents erhalten 200 und starten keine Runs. Outbound sendet nichts.

Einrichtung

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

  2. 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.com stehen 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.

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

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

FeldTypStatusBeschreibung
typestringRequiredgitlab.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringRequiredInbound und Outbound. Name oder ID eines GitLab-Kontozugangs. Dashboard: Connection.
configobjectOptionalEinstellungen der GitLab-Verbindung. Nur bei Inbound; eine Outbound-Verbindung braucht keine.
projectstringRequiredInbound. Der Pfad des Projekts, etwa acme/api, oder seine Nummer. Die Verbindung erhält seine Events. Dashboard: Project.
eventsstring[]RequiredInbound. 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.

WertModiBeschreibung
WebhookInboundDer 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-IDInboundDie 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.
NutzerInbound, OutboundID 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:

payload.json
{
  "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": { ... }
}
  • event ist das Event, wie du es unter events einträgst, und action die Aktion aus GitLab, etwa open oder create.
  • type ist issue oder merge_request, auch bei Kommentaren, und iid die Nummer im Projekt. title ist der Titel.
  • conversation_id bleibt für alle Events eines Issues oder Merge Requests gleich. Soll dein Agent die früheren Kommentare als Verlauf kennen, setze in seiner YAML session.key: input.conversation_id. Von sich aus schaltet der Connector keine Sessions ein.
  • text ist die Beschreibung oder der Kommentar in Markdown und url der Link dorthin.
  • author ist der Nutzername der Person, die das Event ausgelöst hat.
  • raw enthä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.

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

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

LimitWert
GitLab-Version17.4 oder neuer. Ab 19.0 signiert GitLab die Zustellungen.
Antwort an GitLabconnic antwortet sofort und startet die Agenten danach.
Fehlschlagender WebhookNach 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 WebhooksGitLab 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 Kommentars1.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.