GitLab anbinden – gooddeploy

gitlab.com oder eigene Instanz

Eine OAuth-Anwendung gehört immer zu genau einer GitLab-Instanz. Darum gibt es zwei Wege:

	gitlab.com	Eigene GitLab-Instanz
Wer richtet die OAuth-Anwendung ein?	der Betreiber der Plattform, einmal für alle Teams	dein Team selbst, einmal je Instanz
Stand auf gooddeploy	noch nicht eingerichtet; `gooddeploy git connect gitlab` ohne `--host` endet mit „Git-Instanz gih_gitlab_com nicht gefunden“	geht
Befehl zum Verbinden	`gooddeploy git connect gitlab` (sobald eingerichtet)	`gooddeploy git connect gitlab --host <id>`

Die Schritte 1 bis 3 unten brauchst du nur für eine eigene Instanz.

Vorher: Hol dir die neueste CLI mit gooddeploy update (Aktualisieren). Den Befehl gooddeploy git hosts gibt es ab Version 0.1.0-alpha.7; welche Version du hast, zeigt gooddeploy version. Ist gitlab.com einmal eingerichtet, startest du direkt bei Schritt 4.

Eine eigene Instanz muss diese Bedingungen erfüllen:

Sie ist über https auf Port 443 erreichbar, mit einem Zertifikat, dem öffentliche Zertifizierungsstellen vertrauen.
Sie ist aus dem Internet erreichbar. gooddeploy verbindet nur zu öffentlichen Adressen: Eine Instanz, die nur im Firmennetz erreichbar ist (zum Beispiel 10.…, 192.168.… oder localhost), lehnt gooddeploy beim Eintragen ab. Auch eine Adresse, die erst nach der Namensauflösung intern wird, wird bei jedem Aufruf abgewiesen.
Die Adresse darf einen Pfad haben (https://example.com/gitlab), aber weder Benutzer noch ? oder #.

Schritt 1: OAuth-Anwendung in GitLab anlegen

Du brauchst bei GitLab das Recht, eine Anwendung anzulegen. Du kannst sie an drei Stellen anlegen; für ein Team reicht meist die Gruppe:

Gruppe: in der Gruppe unter Einstellungen → Anwendungen.
Benutzer: oben links auf dein Profilbild, dann „Edit profile“ → „Access“ → „Applications“.
Instanzweit: im Admin-Bereich unter Anwendungen (nur Administratoren).

Trage diese Felder ein:

Feld	Wert
Name	frei wählbar, zum Beispiel `gooddeploy`
Redirect URI	`<API-Adresse>/v1/git/callback/gitlab`, auf gooddeploy also `https://api.gooddeploy.de/v1/git/callback/gitlab`
Confidential	an (Standard)
Scopes	nur `api`

Die Redirect-URI ist die öffentliche Adresse der gooddeploy-API (dieselbe, die gooddeploy whoami in der Zeile „Server“ zeigt), gefolgt von /v1/git/callback/gitlab. Sie muss Zeichen für Zeichen stimmen, ohne / am Ende; sonst lehnt GitLab beim Verbinden mit „redirect_uri“ ab. Der Scope api ist nötig, weil gooddeploy Webhooks anlegt und den Status an Commits schreibt.

Nach „Save application“ zeigt GitLab die Application ID und das Secret. Das Secret siehst du nur jetzt; lass die Seite offen, bis du Schritt 2 gemacht hast, oder lege es sicher ab.

Schritt 2: Instanz bei gooddeploy eintragen

Du brauchst die Rolle owner oder admin im Team (Rechte); bist du mit einem Zugangscode angemeldet, braucht er das Recht admin auf allen Projekten des Teams. Trag die Adresse der Instanz und die Application ID ein:

gooddeploy git hosts add https://git.example.com --client-id <Application ID>

gooddeploy fragt das Secret der Anwendung ab; die Eingabe ist verdeckt. Das Secret gibst du nie als Argument an, damit es weder in der Shell-Historie noch in der Prozessliste landet. Gehörst du zu mehreren Teams, wählst du das Team wie bei jedem Befehl mit --team <name>.

Die Ausgabe nennt die ID der Instanz (gih_…) und gleich den nächsten Befehl:

✓ GitLab-Instanz https://git.example.com eingetragen
  Das Secret ist verschlüsselt gespeichert und wird nie wieder angezeigt.
  ID:             gih_01J…
  Application ID: …
  Verbinden:      gooddeploy git connect gitlab --host gih_01J…

Weitere Befehle:

Befehl	Wirkung
`gooddeploy git hosts`	alle Instanzen: die der Plattform und die eigenen des Teams, mit ID und Application ID (nie mit Secret)
`gooddeploy git hosts rm <id>`	eigene Instanz entfernen (mit Rückfrage, ohne Terminal `--yes`); geht nur, solange keine Verbindung sie nutzt

Mit --json gibt jeder Befehl die Antwort der API aus.

Mögliche Fehler beim Eintragen: VALIDATION_FAILED bei einer Adresse ohne https, mit anderem Port als 443, mit interner Adresse oder wenn die Adresse „… eine Instanz der Plattform“ ist (dann verbindest du direkt mit der Instanz der Plattform, eine eigene OAuth-Anwendung ist nicht nötig); SCOPE_MISSING, wenn du nicht owner oder admin bist oder dem Zugangscode das Recht admin auf allen Projekten fehlt.

In Skripten: Ohne Terminal liest gooddeploy git hosts add das Secret aus der ersten Zeile von stdin, zum Beispiel printf '%s' "$GITLAB_SECRET" | gooddeploy git hosts add https://git.example.com --client-id <Application ID>. Ohne CLI geht es direkt über die API mit POST /v1/git/hosts und den Feldern baseUrl, clientId und clientSecret; der Zugangscode gehört dabei nicht als Argument an curl (sonst sieht ihn jeder per ps), sondern zum Beispiel über -K in die Konfiguration:

jq -n --arg url "https://git.example.com" --arg id "<Application ID>" \
  '{baseUrl: $url, clientId: $id, clientSecret: env.GITLAB_SECRET}' |
curl -sS -X POST https://api.gooddeploy.de/v1/git/hosts \
  -K <(printf 'header = "Authorization: Bearer %s"\n' "$GOODDEPLOY_TOKEN") \
  -H "Content-Type: application/json" --data-binary @-

Zugangscodes für die CI und wie du sie setzt, steht unter Skripte und CI.

Schritt 3: Netz prüfen

Zwei Richtungen müssen stimmen:

gooddeploy erreicht GitLab: per https mit gültigem Zertifikat (siehe oben). Dafür fragt gooddeploy Konto, Repos und Branches ab, legt den Webhook an und schreibt den Status an Commits.
GitLab erreicht gooddeploy: Der Webhook schickt Pushes und Merge Requests an die öffentliche API-Adresse (<API-Adresse>/v1/webhooks/gitlab/…, nur https). Deine Instanz muss diese Adresse aufrufen dürfen, dazu auch die Redirect-URI aus dem Browser.

Die GitLab-Einstellung „Allow requests to the local network from webhooks and integrations“ (Admin-Bereich → Einstellungen → Netzwerk → Outbound requests) spielt nur eine Rolle, wenn die API-Adresse aus Sicht deiner Instanz auf eine interne Adresse zeigt, etwa weil deine Instanz sie über ein internes DNS auflöst. Zeigt sie wie üblich auf eine öffentliche Adresse, musst du nichts ändern. Steht dieselbe Einstellung auf „Block all requests, except allowlist“, trage die API-Adresse (bei gooddeploy api.gooddeploy.de) in die Allowlist ein, sonst kommen die Webhooks nicht an. Eine Firewall oder ein Proxy vor deiner Instanz darf ausgehende https-Aufrufe an die API-Adresse nicht blockieren.

Ab GitLab 19.0 signiert GitLab den Webhook; bei älteren Versionen nutzt gooddeploy ein geteiltes Token und zeigt beim Verknüpfen einen Hinweis.

Schritt 4: Instanz verbinden

Ein owner oder admin verbindet die Instanz einmal mit dem Team:

gooddeploy git connect gitlab --host gih_01J…

gooddeploy öffnet den Browser (ohne Browser: --no-browser, dann steht der Link im Terminal). Danach:

Melde dich bei GitLab an und erlaube der Anwendung den Zugriff (Scope api).
gooddeploy zeigt eine Seite mit Team und Person. Bestätige nur, wenn du das gerade selbst gestartet hast und dir beides bekannt ist; hat dir jemand den Link geschickt, klick auf „Abbrechen“.
Im Terminal erscheint „GitLab-Konto … verbunden“ mit der ID der Verbindung (gcn_…). gooddeploy git ls zeigt sie.

Der Link gilt 10 Minuten und nur einmal. Im Dashboard geht dasselbe unter Einstellungen in der Karte „Git-Verbindungen“ (Git-Anbindung); die Instanz selbst trägst du aber immer mit gooddeploy git hosts add ein.

Schritt 5: Projekt mit einem Repo verknüpfen

Projekt zuerst anlegen: „Neues Projekt“ im Dashboard bietet GitLab noch nicht an (kommt später). Leg das Projekt deshalb in der CLI an, im Ordner deines Repos:

gooddeploy link mein-projekt --yes

Verknüpfen kannst du danach auf zwei Wegen: im Dashboard im Projekt unter Einstellungen → „Repo verknüpfen“ oder in der CLI mit gooddeploy git link, wie hier beschrieben. Im Ordner des Projekts (oder mit --project):

gooddeploy git link gruppe/untergruppe/repo

Der Pfad ist der Pfad des Repos in GitLab (gruppe/repo, auch mit Untergruppen). Du brauchst das Recht settings auf dem Projekt und bei GitLab mindestens die Rolle Maintainer im Repo, sonst endet der Befehl mit GIT_PERMISSION_MISSING. Optionen:

Option	Wirkung
`--production-branch <name>`	Produktions-Branch; ohne Angabe der Standard-Branch des Repos
`--previews all`, `--previews list` oder `--previews "staging,release/*"`	für welche Branches Previews entstehen; Standard: Produktions-Branch und offene Merge Requests; `list` allein: nur der Produktions-Branch
`--auto-promote=false`	Pushes auf den Produktions-Branch bauen nur die Preview, live schaltest du von Hand (Standard: automatisch live)
`--connection <id>`	Verbindung (aus `gooddeploy git ls`), wenn mehrere das Repo sehen
`--root`, `--paths`	Ordner und Pfadfilter bei Monorepos

Alle Einzelheiten dazu stehen unter Projekt mit einem Repo verknüpfen.

Im Dashboard verknüpfst du ein GitLab-Repo im Reiter Einstellungen des Projekts mit „Repo verknüpfen“ (Repo im Reiter Einstellungen verknüpfen): Repo wählen, die Branches laden danach von selbst. Hat das Projekt noch kein Deployment, zeigt die Übersicht die Karte „Projekt einrichten“ (erster Schritt „GitLab verbinden“), und der erste Build startet von selbst. Später baust du jeden Branch mit „Jetzt bauen“ im Reiter Einstellungen oder oben auf der Projektseite, in der CLI mit gooddeploy git build --branch <name>.

Beim Verknüpfen legt gooddeploy im Repo einen Webhook an, der bei Pushes und Merge Requests auslöst (keine Tag-, Issue-, Kommentar- oder Pipeline-Ereignisse; die Prüfung des Zertifikats ist an). Du siehst ihn bei GitLab unter Einstellungen → Webhooks; lösche ihn dort nicht von Hand, sondern trenne mit gooddeploy git unlink.

Erster Build: Verknüpfst du im Reiter Einstellungen ein Projekt ohne Deployment, startet der erste Build von selbst (siehe oben). gooddeploy git link startet keinen Build; den ersten Build startest du dann mit gooddeploy git build oder mit einem Push auf den Produktions-Branch, etwa mit einem leeren Commit (bei anderem Branch main ersetzen):

git commit --allow-empty -m "Erster Build mit gooddeploy" && git push origin main

Jeder gebaute Commit bekommt in GitLab einen Status gooddeploy/preview (bei Pushes auf den Produktions-Branch zusätzlich gooddeploy/production), sichtbar am Commit und im Merge Request. Wie der Status aussieht und was er bedeutet, steht unter Was ein Push auslöst.

Fehler und Lösungen

Meldung oder Code	Ursache	Was tun?
„Git-Instanz … nicht gefunden“	Die ID stimmt nicht, die Instanz gehört einem anderen Team, oder du hast `--host` weggelassen und gitlab.com ist noch nicht eingerichtet.	`gooddeploy git hosts` zeigt die Instanzen deines Teams; richtige `gih_…` mit `--host` angeben.
„Der Git-Anbieter gitlab ist auf dieser Plattform nicht eingerichtet“	Für diese Plattform fehlt die Einrichtung von gitlab.com.	Eigene Instanz eintragen (Schritte 1 bis 3) oder warten, bis gitlab.com eingerichtet ist.
„ist eine interne Adresse“ (`VALIDATION_FAILED`)	Die Instanz ist nicht öffentlich erreichbar oder nutzt keinen https-Port 443.	Instanz öffentlich über https bereitstellen.
„GitLab nicht erreichbar“ (`PLATFORM_UNAVAILABLE`)	gooddeploy erreicht die Instanz nicht (Firewall, DNS, abgelaufenes oder fremdes Zertifikat).	Zertifikatskette und Erreichbarkeit von außen prüfen.
„GitLab lehnt die OAuth-Anwendung ab“	Application ID oder Secret stimmen nicht.	Anwendung in GitLab prüfen; das Secret ist nur einmal sichtbar. Verbindung trennen, Instanz mit `gooddeploy git hosts rm <id>` entfernen und mit den richtigen Werten neu eintragen.
GitLab zeigt „redirect_uri is invalid“	Die Redirect-URI der Anwendung stimmt nicht mit `<API-Adresse>/v1/git/callback/gitlab` überein.	Feld bei GitLab korrigieren, Zeichen für Zeichen.
„Dieser Link zum Verbinden ist abgelaufen“ oder „schon benutzt“	Der Link gilt 10 Minuten und nur einmal.	`gooddeploy git connect gitlab --host <id>` noch einmal starten.
„Die Freigabe beim Git-Anbieter wurde abgelehnt“	Im Browser wurde „Deny“ gewählt.	Verbinden neu starten und den Zugriff erlauben.
`SCOPE_MISSING` („nur owner und admin des Teams“)	Eintragen und Verbinden dürfen nur owner und admin.	Rolle im Team prüfen (Rechte).
`GIT_PERMISSION_MISSING`	Beim Verknüpfen: Du hast im Repo nicht mindestens die Rolle Maintainer, oder das Konto sieht das Repo nicht.	Rolle in GitLab vergeben lassen und erneut verknüpfen.
`GIT_CONNECTION_BROKEN`	Der Zugriff wurde in GitLab widerrufen oder die verbindende Person ist nicht mehr im Repo.	Mit `gooddeploy git connect gitlab --host <id>` neu verbinden.
Ein Push baut nichts	Der Webhook erreicht gooddeploy nicht, oder der Branch hat laut „Previews bauen für“ keine Preview.	Bei GitLab unter Einstellungen → Webhooks die letzten Aufrufe ansehen; Netz wie in Schritt 3 prüfen.

Weitere Codes stehen unter Häufige Fehler.

Trennen

gooddeploy git unlink trennt ein Projekt vom Repo und löscht den Webhook. gooddeploy git disconnect trennt die ganze Verbindung (owner und admin; gooddeploy nimmt den Zugriff bei GitLab zurück und löscht die gespeicherten Zugangsdaten, siehe Trennen). Die Instanz selbst bleibt eingetragen, bis du sie mit gooddeploy git hosts rm <id> entfernst; das geht nur, solange keine Verbindung sie nutzt (sonst nennt die Meldung die Verbindung, die du zuerst mit gooddeploy git disconnect <id> trennst). Wenn du eine OAuth-Anwendung in GitLab löschst, gilt die Verbindung als unterbrochen (GIT_CONNECTION_BROKEN).