GitLab Self-Managed

Voraussetzungen

Eine GitLab-Instanz (z.B. https://gitlab.ihre-firma.de) mit Netzwerkzugriff von und zu KI-DACH
Ein GitLab-Konto mit Zugriff auf die Projekte, die Sie verbinden möchten
Mindestens Developer-Zugriff auf die jeweilige Gruppe oder die Projekte

Access Token erstellen

KI-DACH benötigt ein Access Token, um auf Ihre GitLab-Repositories zugreifen und Webhooks einrichten zu können.

Personal Access Token

Melden Sie sich bei Ihrer GitLab-Instanz an — idealerweise mit einem dedizierten Service-Account.
Navigieren Sie zu Einstellungen > Access Tokens.
Klicken Sie auf Add new token und vergeben Sie einen aussagekräftigen Namen, z.B. KI-DACH.
Wählen Sie den Scope api aus. Dieser ist erforderlich für den vollen Funktionsumfang (Merge Requests, Kommentare, Webhooks).
Setzen Sie optional ein Ablaufdatum. Ohne Angabe gilt standardmäßig ein Jahr.
Klicken Sie auf Create personal access token und kopieren Sie den Token-Wert sofort — er wird nur einmal angezeigt.

Project Access Token

Alternativ können Sie ein Project Access Token verwenden, das auf ein einzelnes Projekt beschränkt ist.

Navigieren Sie zum gewünschten Projekt und öffnen Sie Einstellungen > Access Tokens.
Erstellen Sie ein neues Token mit dem Scope api und der Rolle Maintainer.
Kopieren Sie den Token-Wert.

Empfehlung: Dedizierten Account nutzen

Wir empfehlen, einen separaten GitLab-User als Service-Account für KI-DACH anzulegen. Vorteile:

Reviews und Kommentare erscheinen unter einem eigenen Bot-Account
Zugriffsrechte lassen sich unabhängig verwalten
Bei Team-Änderungen bleibt die Integration bestehen

Empfohlene Einstellungen für den Service-Account:

Benutzername: ki-dach oder ki-dach-bot
E-Mail: Eine dedizierte Adresse, z.B. ki-dach@ihre-firma.de
Zugriff: Mindestens Developer auf die relevante Gruppe oder die Projekte

Mit KI-DACH verbinden

Öffnen Sie das KI-DACH-Dashboard und navigieren Sie zu Integrationen > GitLab Self-Managed.
Klicken Sie auf GitLab Self-Managed verbinden.
Geben Sie die URL Ihrer GitLab-Instanz ein, z.B. https://gitlab.ihre-firma.de.
Fügen Sie Ihr Access Token ein (beginnt mit glpat-...).
Klicken Sie auf Verbinden. KI-DACH validiert das Token und die Erreichbarkeit Ihres Servers.

Nach erfolgreicher Verbindung werden Ihre GitLab-Projekte automatisch synchronisiert und in der Übersicht angezeigt.

Projekte konfigurieren

Nach dem Verbinden können Sie für jedes Projekt individuell festlegen, welche Funktionen aktiv sein sollen.

Merge-Request-Reviews

Automatisch bei Erstellung — KI-DACH Agent erstellt automatisch ein Review, wenn ein neuer Merge Request geöffnet wird.
Bei Label — KI-DACH Agent erstellt ein Review, wenn das Label ki-dach dem Merge Request zugewiesen wird.

Issue-Automatisierung

Bei Label — KI-DACH Agent verarbeitet Issues, die mit dem Label ki-dach versehen werden.

Aktivieren Sie die gewünschten Optionen pro Projekt über den Schalter in der Projektliste. Beim Aktivieren eines Projekts wird automatisch ein Webhook auf Ihrer GitLab-Instanz eingerichtet.

Token aktualisieren

Falls Ihr Access Token abläuft oder Sie es erneuern möchten:

Erstellen Sie ein neues Token auf Ihrer GitLab-Instanz (siehe Access Token erstellen).
Öffnen Sie die GitLab-Self-Managed-Integration im KI-DACH-Dashboard.
Verwenden Sie die Option Access Token aktualisieren bei der betroffenen Verbindung.
Geben Sie das neue Token ein — das bestehende wird ersetzt.

Fehlerbehebung

Ungültiges Access Token

Ungültiges Access Token. Bitte überprüfen Sie, ob Ihr Token korrekt ist, nicht abgelaufen ist und die erforderliche Berechtigung hat (api).

Stellen Sie sicher, dass der Token den Scope api besitzt
Prüfen Sie, ob der Token abgelaufen ist
Erstellen Sie bei Bedarf einen neuen Token

Unzureichende Berechtigungen für Webhooks

Ihr Access Token hat nicht die erforderlichen Berechtigungen, um Webhooks zu erstellen.

Bei einem Project Access Token ist mindestens die Rolle Maintainer erforderlich
Bei einem Personal Access Token stellen Sie sicher, dass der Scope api vorhanden ist
Prüfen Sie, ob der User mindestens Developer-Zugriff auf das Projekt hat

GitLab-Server nicht erreichbar

Der GitLab-Server konnte nicht erreicht werden. Bitte überprüfen Sie, ob die URL korrekt ist und der Server erreichbar ist.

Überprüfen Sie die eingegebene URL auf Tippfehler
Stellen Sie sicher, dass der Server über das Internet erreichbar ist (keine Firewall-Blockade, VPN-Anforderungen etc.)
Prüfen Sie, ob HTTPS korrekt konfiguriert ist und ein gültiges SSL-Zertifikat vorliegt

Webhook konnte nicht erstellt werden

Der Webhook konnte nicht auf GitLab erstellt werden.

Stellen Sie sicher, dass Ihr Token den Scope api besitzt und der User ausreichende Berechtigungen hat
Prüfen Sie in den Admin-Einstellungen Ihrer GitLab-Instanz, ob ausgehende Webhook-Anfragen an externe Dienste erlaubt sind
Unter Admin > Einstellungen > Netzwerk > Outbound Requests muss ggf. die Ziel-URL freigeschaltet werden

Projekt nicht gefunden

Das Projekt wurde auf GitLab nicht gefunden.

Stellen Sie sicher, dass der Token-User Zugriff auf das betroffene Projekt hat
Synchronisieren Sie die Projektliste über die Schaltfläche in der Übersicht