Für Skripte und CI

Anmelden ohne login

In der CI setzt du den Zugangscode als geschützte Variable GOODDEPLOY_TOKEN. gooddeploy nimmt ihn dann statt der Datei aus gooddeploy login.

Farben (grünes ✓, rotes ✗) gibt es nur, wenn gooddeploy direkt ins Terminal schreibt. Leitest du die Ausgabe in eine Datei oder ein anderes Programm um oder nutzt du --json, kommt sie ohne Farben und ohne mitlaufende Fortschrittszeile.

Gib dem Zugangscode in der CI nur die Rechte, die die Pipeline braucht, z. B. read und deploy für Previews (siehe Rechte).

Ohne Rückfragen

Ohne Terminal fragt gooddeploy nie nach, sondern bricht mit Exit-Code 1 ab und sagt, welche Option fehlt:

rollback fragt nie nach. Ein unbekanntes Projekt legen deploy und link ohne Terminal nie nebenbei an: Sie enden mit NOT_FOUND (Exit-Code 1) und dem Hinweis auf gooddeploy link <name>. Lege neue Projekte deshalb einmal im Terminal an oder im Skript mit gooddeploy link <name> --yes.

Beispiel für eine Pipeline, die jeden Commit als Preview baut und main live schaltet. link --yes verknüpft den frischen Checkout und legt das Projekt beim ersten Lauf an. deploy findet das Projekt danach auch ohne --project; gibst du --project oder GOODDEPLOY_PROJECT an, muss es dasselbe Projekt sein wie bei link:

gooddeploy link kunde-website --yes
gooddeploy deploy --project kunde-website --json > deploy.ndjson
if [ "$CI_COMMIT_BRANCH" = "main" ]; then
  gooddeploy promote --project kunde-website --yes --wait
fi

Eigene Prüfungen, etwa E2E-Tests gegen die Preview, meldet die Pipeline mit gooddeploy checks report <id> <name> success|failure an das Deployment (siehe Logs, Checks und Datenbank; kommt später).

promote ohne ID nimmt die neueste Preview des Projekts. Laufen mehrere Pipelines parallel, gib die ID aus dem Deploy mit (Feld deployment.shortId im Ergebnis).

Ausgabe im Terminal, in Pipes und in der CI

Im Terminal zeigt gooddeploy Farben, Kästen, Etiketten und während längerer Schritte einen Spinner mit der laufenden Zeit. Das stellt es selbst um, ohne Einstellung:

Nichts ist nur an der Farbe zu erkennen: Zeichen (✓, ✗, ●) und Wörter tragen die Bedeutung. In iTerm2, WezTerm, VS Code und einigen anderen Terminals sind Adressen anklickbar. Fehler nennen immer ihren Code und den Exit-Code (Code SCOPE_MISSING · Exit 3).

Ausgabe mit --json

Mit --json (vor oder nach dem Befehl) schreibt gooddeploy eine JSON-Zeile je Ereignis auf die Standardausgabe (NDJSON) und keine Fortschrittszeilen für Menschen.

• status, ls, whoami, logout, link, inspect (ohne --wait), protect, rm, projects rm, update, launch, open, version: genau eine Zeile mit dem Ergebnis. version liefert version (mit Commit in Klammern, wie bisher) und zusätzlich das Feld commit.
• login mit Zugangscode: eine Zeile; login --email: zuerst {"event":"device","userCode":…} mit dem Code für die Bestätigungsseite, dann das Ergebnis mit userEmail und expiresAt.
• inspect --wait: Zustandswechsel wie bei deploy, zuletzt {"deployment":…}, bei einem Fehler mit Feld error.
• deploy: zuerst {"event":"uploaded",…}, dann je Zustandswechsel {"event":"state","id":…,"state":…,"from":…,"elapsedMs":…,"phaseMs":…}, zuletzt {"event":"result",…} mit status, deployment, previewUrl und durationMs; bei einem gescheiterten Build zusätzlich logTail mit den letzten Zeilen des Build-Logs, soweit die Plattform es liefert. Mit --json --stream kommen dazwischen auch die Ereignisse der Plattform, erkennbar am Feld type statt event: log (Zeile im Build-Log), phase, check und status (kommt später; bis dahin gibt es nur die Zeilen mit event).
• env add: je Umgebung {"event":"env",…} mit variable (ohne Wert), warnings und bei --apply deployment; env rm: je Umgebung {"event":"env-removed",…}; env ls und env pull: eine Zeile, nie mit Werten.
• logs: je Log-Zeile ein Objekt mit line, node, stream und at. checks report, db info, db dump: eine Zeile mit dem Ergebnis.
• promote und rollback: Zustandswechsel wie oben, mit --wait zusätzlich {"event":"live",…}, sobald die Version live ist, und zuletzt {"event":"result",…} mit liveUrls, productionUrl, liveAfterMs und from (die vorherige Live-Version).

Die letzte Zeile ist immer das Ergebnis, auch bei Fehlern. Scheitert ein Deploy, Promote oder Rollback, enthält das result ein Feld error. Andere Fehler kommen als:

{"error":{"code":"SCOPE_MISSING","message":"Recht \"deploy\" für Projekt kunde-website fehlt.","hint":"…","requestId":"req_…"}}

Ohne --json stehen Fehler als ✗ Meldung mit → Hinweis auf der Fehlerausgabe. Die requestId hilft goodDEV, einen Fehler schnell zu finden; gib sie bei Rückfragen mit an.

Meldet die Plattform einen gescheiterten Deploy, Promote oder Rollback ausnahmsweise ohne Fehlercode, endet gooddeploy trotzdem nie mit 0. Auch ein Absturz von gooddeploy selbst endet mit INTERNAL und Exit-Code 6, ohne technische Details; die zeigt GOODDEPLOY_DEBUG=1.

Exit-Codes

Ein unbekannter Fehlercode (etwa von einer neueren Plattform) endet ebenfalls mit 6. Pflicht-Checks (REQUIRED_CHECK_…), Build-Variablen (BUILD_ENV_…), Projekteinstellungen (CONFIG_INVALID), die Prüfung auf Geheimnisse im Build (SECRET_IN_IMAGE) und die Anmeldung per Link (LOGIN_LINK_…, LOGIN_CODE_INVALID) kommen später; die Codes sind schon festgelegt, damit Skripte stabil bleiben. Was die einzelnen Codes bedeuten und was du tun kannst, steht unter Häufige Fehler.