Git-Anbindung

Verknüpfe dieses Projekt mit seinem GitHub-Repo, damit Pushes Previews bauen.
Lies zuerst https://docs.gooddeploy.eu/git-anbindung.html und richte dich genau danach; rate keine Befehle. Steht dort oder meldet gooddeploy, dass die Git-Anbindung bzw. der Git-Anbieter nicht eingerichtet ist, sag mir das und hör auf.
Zeig mir mit gooddeploy git ls die Verbindungen des Teams. Fehlt eine, starte gooddeploy git connect; bestätigen tue ich selbst im Browser.
Frag mich nach Produktions-Branch, wofür Previews gebaut werden sollen (Standard: Produktions-Branch und offene Pull Requests) und, bei Monorepos, Wurzelordner, und führe gooddeploy git link <owner/repo> erst nach meinem OK aus.
Leitplanken: gooddeploy promote, gooddeploy rollback, Löschen (rm) und Änderungen an Rechten nur nach ausdrücklicher Rückfrage bei mir. Schreibe oder gib nie Passwörter, Tokens oder Werte von Umgebungsvariablen im Chat aus.

Stand: Die Git-Anbindung ist auf gooddeploy für GitHub eingeschaltet (seit 7. November 2026). gitlab.com ist noch nicht eingerichtet; gooddeploy git connect gitlab ohne --host endet deshalb mit dem Fehler „Git-Instanz gih_gitlab_com nicht gefunden“ und dem Hinweis auf die eingerichteten Instanzen. Eine eigene GitLab-Instanz deines Teams geht (Schritt für Schritt unter GitLab anbinden). Ohne Git-Anbindung deployst du weiter mit gooddeploy deploy oder aus deiner CI (Skripte und CI).

Den Schalter für die Git-Anbindung hat der Betreiber der Plattform. Ist sie aus (zum Beispiel auf einer anderen Plattform), melden gooddeploy git … und die API „Die Git-Anbindung ist auf dieser Plattform noch nicht eingeschaltet.“ und das Dashboard zeigt den Reiter Einstellungen nicht; deployen kannst du dann weiter mit gooddeploy deploy.

Neues Projekt im Dashboard

Am schnellsten geht ein neues Projekt im Dashboard: „Neues Projekt“ oben auf der Seite Projekte bzw. der Übersicht (in einem Team ohne Projekte „Erstes Projekt anlegen“). Du hast zwei Wege:

• Mit GitHub verbinden (empfohlen): Das Dashboard führt dich in Schritten durch.
• Mit der CLI: gooddeploy deploy im Ordner der Website (Erste Schritte).

Der Weg über GitHub:

1. GitHub verbinden: Hat dein Team noch kein Git-Konto, verbindet ein owner oder admin es hier einmal („GitHub verbinden“, weiter wie unten unter Git-Konto verbinden). Die Seite wartet, bis du im neuen Tab bestätigt hast, und geht dann von selbst weiter.
2. Repo wählen: Du siehst alle Repos, die gooddeploy bei GitHub sehen darf, mit Suche. Ist ein Repo schon mit einem Projekt verknüpft, steht das dabei. Fehlt ein Repo, hilft der Kasten „Repo fehlt?“ unter der Liste: „Weiteres Konto verbinden oder Repos freigeben“ (nur owner und admin) öffnet GitHub in einem neuen Tab. Dort wählst du ein weiteres Konto oder eine Organisation, oder du wählst ein schon verbundenes Konto mit „Configure“ und gibst weitere Repos frei. Danach lädt die Liste von selbst neu; mit „Liste neu laden“ holst du sie jederzeit frisch, zum Beispiel nachdem jemand anderes die Freigabe bei GitHub geändert hat.
3. Name und Branches: gooddeploy schlägt einen Namen aus dem Repo vor (Regeln wie bei gooddeploy link: 3–30 Zeichen, a-z, 0-9 und einzelne Bindestriche). Den Produktions-Branch wählst du aus den Branches des Repos; vorgewählt ist der Standard-Branch (meist main). Unter Previews bauen für wählst du, welche Pushes eine Preview bekommen: „Produktions-Branch und Pull Requests“ (vorgewählt und empfohlen), „Jeder Branch“ oder „Nur diese Branches“ mit einer Liste wie staging, release/* (siehe Was ein Push auslöst). Unter Push auf den Produktions-Branch wählst du „Automatisch live schalten“ (vorgewählt) oder „Nur Preview bauen, live per Klick“, etwa wenn erst dein Kunde die Preview freigeben soll (siehe Nur Preview, live per Klick). Optional legst du gleich Postgres an und gibst bei einem Monorepo den Wurzelordner an.
4. Anlegen und verknüpfen: „Projekt anlegen“ legt das Projekt an und verknüpft es gleich mit dem Repo.
5. Erster Build: Direkt nach dem Verknüpfen startet „Jetzt bauen“ von selbst: gooddeploy holt den neuesten Stand des Produktions-Branches (zum Beispiel main) und baut daraus eine Preview, ganz ohne Push. Sobald das Deployment angelegt ist, springt die Seite dorthin und du siehst das Build-Log live; danach steht dort die Preview-Adresse. Den Knopf „Jetzt bauen“ findest du auch auf der Seite, falls der erste Build nicht von selbst startet (zum Beispiel ohne JavaScript) oder du ihn noch einmal anstoßen willst. Ist das Repo noch leer, sagt dir die Seite das; dann startet dein erster Push den Build. Alternativ geht es weiter per Push, etwa mit einem leeren Commit: git commit --allow-empty -m "Erster Build mit gooddeploy" && git push origin main.

Der erste Build bleibt eine Preview, auch auf dem Produktions-Branch. Live schaltest du ihn mit einem Klick auf der Seite des Deployments (oder gooddeploy promote); jeder weitere Push auf den Produktions-Branch geht nach dem Build automatisch live (siehe unten), außer du hast „Nur Preview bauen, live per Klick“ gewählt.

Rechte: Anlegen und „Jetzt bauen“ brauchen das Recht deploy, Repos sehen und verknüpfen das Recht settings, beides für alle Projekte des Teams; das Git-Konto verbinden nur owner und admin (Rechte). Fehlt dir ein Recht, zeigt das Dashboard den Grund statt des Knopfs. Ist die Git-Anbindung auf der Plattform aus, steht beim Weg über GitHub „kommt bald“; der Weg über die CLI geht immer.

Produktions-Branch, Previews und „Push auf den Produktions-Branch“ änderst du später im Reiter Einstellungen des Projekts („Ändern“ bei Git-Repository); dort stehen die Einstellungen auch in den Zeilen „Previews für“ und „Live schalten“. Kommt später: GitLab (gitlab.com oder eigene Instanz) als eigener Weg unter „Neues Projekt“ (bis dahin verknüpfst du ein GitLab-Repo im Reiter Einstellungen, siehe unten), Pfadfilter schon beim Anlegen wählen (bis dahin in den Einstellungen des Projekts).

Repo im Reiter Einstellungen verknüpfen

Ein bestehendes Projekt (zum Beispiel mit gooddeploy deploy angelegt) verknüpfst du im Reiter Einstellungen des Projekts in der Karte „Git-Repository“ mit „Repo verknüpfen“. Der Dialog nennt im Titel das Projekt („Repo verknüpfen: shop“), damit du nicht versehentlich das falsche erwischst:

• Repo: Am Anfang ist keins gewählt („Bitte Repo wählen“); speichern geht erst, wenn du eins gewählt hast.
• Produktions-Branch: Nach der Wahl des Repos stehen hier seine Branches, vorgewählt ist der Standard-Branch des Repos. Wechselst du das Repo, lädt die Liste neu. Ohne JavaScript steht hier „Standard-Branch des Repos“, gooddeploy nimmt dann den Standard-Branch.
• Previews bauen für: wie beim Anlegen (siehe Was ein Push auslöst). Das Feld Branches erscheint nur bei „Nur diese Branches“; lässt du es leer, baut nur der Produktions-Branch. Auf schmalen Bildschirmen stehen die drei Möglichkeiten untereinander.
• Push auf den Produktions-Branch, Wurzelordner und Pfadfilter wie beim Anlegen.
• Nicht bauen bei Änderungen nur in …: Muster für Dateien, deren Änderung allein keinen Build auslöst, z. B. docs/**, **/*.md (siehe Builds überspringen). Leer heißt: keine Ausnahme.

Hat das Projekt noch kein Deployment, führt „Verknüpfen“ in die Übersicht des Projekts: Dort steht die Karte Projekt einrichten mit den Schritten bis zum ersten Build, und der erste Build startet von selbst wie beim Anlegen (ohne JavaScript per Knopf „Jetzt bauen“). Die Karte bleibt in der Übersicht, solange das Projekt verknüpft ist und noch kein Deployment hat; sobald das erste Deployment da ist, springt sie auf dessen Seite mit dem Build-Log. Bei einem GitLab-Repo heißt der erste Schritt „GitLab verbinden“. Hat das Projekt schon Deployments, bleibt es beim Reiter Einstellungen.

Jetzt bauen

„Jetzt bauen“ baut den neuesten Stand eines Branches sofort, ohne Push, und zwar neu, auch wenn dieser Stand schon gebaut wurde (etwa nach einem gescheiterten Build oder einer geänderten Build-Variable). Du findest es dauerhaft im Reiter Einstellungen in der Karte „Git-Repository“ und oben auf der Projektseite. Im Fenster wählst du den Branch (vorgewählt ist der Produktions-Branch; ohne das Recht settings tippst du den Namen ein). Danach zeigt die Projektseite das neue Deployment, sobald es angelegt ist, mit „Log live ansehen“. Der Build bleibt eine Preview, auch auf dem Produktions-Branch; live gehen kann nur ein Build des Produktions-Branches (Live geht nur der Produktions-Branch). „Jetzt bauen“ geht für jeden Branch, egal was unter „Previews bauen für“ steht. Dafür brauchst du das Recht deploy. Gibt es den Branch nicht (oder ist das Repo noch leer), sagt es die Seite mit dem Code NOT_FOUND.

In der CLI geht dasselbe im Ordner des Projekts (oder mit --project):

gooddeploy git build                       # Produktions-Branch
gooddeploy git build --branch feature/login

Die Ausgabe nennt Branch, Repo und Commit; das Deployment erscheint kurz danach in gooddeploy ls. Mit --json kommt die Antwort der API. Fehler: NOT_FOUND (Projekt nicht verknüpft oder Branch gibt es nicht, Exit-Code 1), GIT_CONNECTION_BROKEN (Git-Konto neu verbinden), PROJECT_LOCKED.

Git-Konto verbinden

Ein owner oder admin des Teams verbindet einmal ein Konto:

gooddeploy git connect github

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

1. GitHub: Installiere die gooddeploy-App und wähle die Repos aus, die gooddeploy bauen darf (alle oder nur ausgewählte). GitLab: Erlaube gooddeploy den Zugriff; gooddeploy bittet um den Scope api, weil es Webhooks anlegt und den Status an Commits schreibt.
2. Danach zeigt gooddeploy eine Seite mit Team und Person, die das Verbinden gestartet haben. Bestätige nur, wenn du das gerade selbst gestartet hast und dir beides bekannt ist. Hat dir jemand den Link geschickt, klick auf „Abbrechen“.
3. Im Terminal erscheint „GitHub-Konto … verbunden“.

Im Dashboard geht das unter Einstellungen (in der Navigation links, Gruppe Team) in der Karte „Git-Verbindungen“: Anbieter wählen, „Git verbinden“, im neuen Tab bestätigen; die Seite aktualisiert sich von selbst. Das Repo verknüpfst du danach im Reiter Einstellungen des Projekts (siehe Reiter eines Projekts) oder gleich beim Anlegen unter „Neues Projekt“.

Der Link gilt 10 Minuten und nur einmal. GitLab: gitlab.com ist auf gooddeploy noch nicht eingerichtet. Eine eigene GitLab-Instanz trägst du zuerst mit gooddeploy git hosts add <adresse> --client-id <id> ein und verbindest sie dann mit gooddeploy git connect gitlab --host <id>; die ganze Anleitung steht unter GitLab anbinden.

Verbindest du dasselbe Konto (bzw. dieselbe GitHub-Installation) noch einmal, erneuert gooddeploy die bestehende Verbindung; verknüpfte Projekte bleiben verknüpft. Eine GitHub-Installation gehört genau einem gooddeploy-Team: Ist sie schon mit einem anderen Team verbunden, endet das Verbinden mit GIT_INSTALLATION_IN_USE.

Verbindungen ansehen

gooddeploy git ls

zeigt jede Verbindung mit Anbieter, Konto, Stand und den verknüpften Projekten:

Git-Verbindungen
  ID                              ANBIETER  KONTO    STAND  PROJEKTE
  gcn_01JQC70000000000000000GH01  GitHub    gooddev  aktiv  shop ← gooddev/shop

Steht dort „unterbrochen – neu verbinden“, verbinde das Konto noch einmal mit gooddeploy git connect.

Im Dashboard stehen die Verbindungen unter Einstellungen in der Karte „Git-Verbindungen“: Anbieter, Konto oder Organisation, Stand, wie viele und welche Projekte verknüpft sind und seit wann die Verbindung besteht. Sehen kann die Karte jedes Mitglied des Teams; verbinden und trennen nur owner und admin.

Projekt mit einem Repo verknüpfen

Im Ordner des Projekts (oder mit --project):

gooddeploy git link gooddev/shop

Dafür brauchst du auf dem Projekt das Recht settings (Rechte). Wer settings auf einem Projekt hat, kann es mit jedem Repo verknüpfen, das eine Verbindung des Teams sieht; gib der App bzw. dem GitLab-Konto deshalb nur Zugriff auf die Repos, die gooddeploy wirklich bauen soll. Ohne weitere Angaben gilt:

• Produktions-Branch: der Standard-Branch des Repos beim Verknüpfen (meist main); ändern mit --production-branch release. Ein Push darauf schaltet automatisch live (siehe unten). Benennst du den Standard-Branch später im Repo um, verknüpfe neu oder gib --production-branch an.
• Previews: für den Produktions-Branch und Branches mit offenem Pull bzw. Merge Request. Ändern mit --previews all (jeder Branch) oder --previews "staging,release/*" (nur diese Branches und der Produktions-Branch; * steht für beliebige Zeichen, auch /). --previews production-and-requests stellt den Standard wieder her. Mit --previews list baut nur der Produktions-Branch, alle anderen Branches nicht (einzelne baust du dann mit gooddeploy git build --branch <name>). Ein einzelnes Muster gibst du einfach so an: --previews staging. Wörter, die nach einer Regel klingen (list als Teil einer Liste, alle, none, keine, default, standard, on, off, aus, an, true, false, in beliebiger Schreibweise), lehnt gooddeploy ab (VALIDATION_FAILED, Exit-Code 1), damit ein Tippfehler nicht still zur Liste mit einem Branch dieses Namens wird. Heißt ein Branch wirklich so, nimm ein Muster wie list*. git link ersetzt die ganze Verknüpfung: Ohne --previews gilt wieder der Standard.
• Automatisch live schalten: an. Mit --auto-promote=false bauen Pushes auf den Produktions-Branch nur die Preview, live schaltest du von Hand (siehe Nur Preview, live per Klick); --auto-promote=true schaltet es wieder an. Anders als bei --previews bleibt ohne Angabe die bisherige Einstellung, damit ein erneutes git link nichts still wieder live schaltet.
• Wurzelordner: das ganze Repo.
• Nicht bauen bei: nichts ausgenommen. Mit --skip-paths "docs/**,**/*.md" baut ein Push nicht, der nur solche Dateien ändert (siehe Builds überspringen). Wie --paths gilt ohne Angabe wieder: keine Ausnahme.
• Verbindung: die einzige, die das Repo sieht. Sehen es mehrere, wähle eine mit --connection <id> (aus git ls).

Bei GitLab legt gooddeploy im Repo einen Webhook an; dafür brauchst du dort mindestens die Rolle Maintainer, sonst endet der Befehl mit GIT_PERMISSION_MISSING (mehr unter GitLab anbinden). Bei GitHub ist nichts weiter nötig, die App bringt ihren Webhook mit.

gooddeploy status zeigt die Verknüpfung in der Zeile „Git“, zum Beispiel gooddev/shop · GitHub · Produktions-Branch main · Previews: main und offene Pull/Merge Requests · live automatisch (bzw. live per Klick (gooddeploy promote)).

Zweite Live-Umgebung, z. B. staging

Eine zweite Live-Umgebung im selben Projekt kommt mit 0.3.0. Bis dahin legst du ein zweites Projekt an und verknüpfst es mit demselben Repo und dem Produktions-Branch staging:

gooddeploy git link gooddev/shop --project shop-staging --production-branch staging --previews staging

Ein Push auf staging geht dann in shop-staging automatisch live. Im ersten Projekt (Produktions-Branch main) baut derselbe Push nach der Standard-Regel nichts, solange es für staging keinen offenen Pull Request gibt. Damit sich die beiden Projekte am Commit nicht gegenseitig den Status überschreiben, bekommt das zweite Projekt eigene Status-Namen (gooddeploy/preview/shop-staging und gooddeploy/production/shop-staging); das erste behält seine. Variablen, Domains und Datenbank richtest du im zweiten Projekt eigens ein.

Was ein Push auslöst

Welche Pushes eine Preview bauen, legt die Einstellung Previews bauen für des Projekts fest:

Pushes auf andere Branches bauen nichts und setzen keinen Status am Commit. Öffnest du einen Pull Request für einen Branch, der schon gepusht ist, baut gooddeploy sofort die Preview seines neuesten Commits; jeder weitere Push auf den Branch baut wieder. Pull Requests aus Forks bauen nie (keine Preview-Secrets für fremden Code). „Jetzt bauen“ geht für jeden Branch, egal was eingestellt ist. Bei einem GitLab-Repo, das schon vor Einführung der Branch-Regeln verknüpft war, baut ein neuer Merge Request erst mit dem nächsten Push; verknüpfst du neu (gooddeploy git unlink, dann git link), baut schon das Öffnen.

Für Projekte, die schon vorher verknüpft waren, gilt seit Einführung der Branch-Regeln ebenfalls der Standard; wer weiter jeden Branch bauen will, stellt „Jeder Branch“ ein.

• Ein Push, der eine Preview baut, baut sie aus genau diesem Commit. Am Commit (und im Pull bzw. Merge Request) erscheint der Status gooddeploy/preview: erst „wartet“, dann „läuft“, am Ende Erfolg mit der Preview-Adresse oder Fehler mit der Meldung.
• Als Nachricht des Deployments (in gooddeploy ls, gooddeploy status und im Dashboard) steht die erste Zeile deiner Commit-Nachricht, ohne Steuerzeichen und auf 255 Zeichen gekürzt; der Branch steht wie bisher daneben. Nur wenn der Commit keine lesbare Nachricht hat, steht dort „Push auf <branch>“ bzw. „Jetzt bauen auf <branch>“. Der Status am Commit bleibt wie oben beschrieben.
• Jeder gebaute Branch hat zusätzlich eine feste Adresse <projekt>-git-<branch>.<domain>, die immer auf die neueste Preview dieses Branches zeigt. Die Projektseite im Dashboard zeigt sie in der Karte „Branch-Adressen“; ein Klick auf den Branch öffnet sie in einem neuen Tab über einen kurzen Freigabelink (1 Tag, wie „Preview“ bei einem Deployment), ohne das Recht deploy steht dort nur der Name. Jedes Deployment zeigt in Liste und Detail seinen Branch. Der Branch-Name wird dafür vereinfacht: klein geschrieben, alles außer Buchstaben und Ziffern wird zu -. Deshalb teilen sich zum Beispiel feature/login und feature-login dieselbe Branch-Adresse; sie zeigt dann auf die Preview, die zuletzt fertig wurde. Die Adresse jeder einzelnen Preview bleibt eindeutig. Branch-Adressen sind wie Previews geschützt: Einen Freigabelink erzeugst du mit gooddeploy share --branch <branch> oder im Dashboard in der Karte „Branch-Adressen“ mit „Mit Kunden teilen“; er zeigt immer die neueste Preview des Branches (Freigabelink).
• Branch-Adressen räumen sich selbst auf: Löschst du einen Branch, verschwindet seine Adresse sofort. Wird ein Pull bzw. Merge Request gemergt oder geschlossen und baut der Branch danach nach deiner Regel keine Previews mehr (Standard: kein weiterer offener Request), verschwindet sie ebenso. Läuft die Preview ab, auf die die Adresse zeigt, oder entfernst du sie mit gooddeploy rm, zeigt die Adresse auf die neueste noch vorhandene Preview des Branches; gibt es keine mehr, verschwindet sie. Einmal am Tag gleicht gooddeploy außerdem alle Branch-Adressen mit den Branches bei GitHub bzw. GitLab ab, falls eine Benachrichtigung verloren ging. Die Previews selbst bleiben unter ihrer eigenen Adresse erreichbar, bis sie nach den üblichen Fristen ablaufen. Freigabelinks für eine entfernte Branch-Adresse funktionieren nicht mehr.
• Ein zweiter Push desselben Commits baut nicht noch einmal, solange der erste Build läuft oder seine Preview steht. Ist der Build gescheitert (zum Beispiel BUILD_TIMEOUT) oder die Preview abgelaufen oder entfernt, baut derselbe Commit beim nächsten Push neu.
• „Jetzt bauen“ baut immer neu, auch wenn der Commit schon eine Preview hat, zum Beispiel nach einer geänderten Build-Variable oder nach einem gescheiterten Build. Nur solange ein Build desselben Commits noch läuft, entsteht kein zweites Deployment (ein Doppelklick baut also einmal). Pushst du genau den Commit, den „Jetzt bauen“ gerade noch baut, auf den Produktions-Branch, geht er nicht automatisch live; schalte ihn dann mit gooddeploy promote live. Ein späterer Push schaltet wie gewohnt automatisch.
• „Jetzt bauen“ (im Dashboard auf der Einrichtungsseite eines neuen Projekts, im Reiter Einstellungen und auf der Projektseite, in der CLI gooddeploy git build, sonst über die API) baut den aktuellen Stand eines Branches wie ein Push, mit demselben Status am Commit. Unterschiede: Es baut immer, auch wenn bei einem Monorepo der letzte Commit den Ordner des Projekts nicht berührt, und es schaltet nie automatisch live.
• Git-Submodule und Git LFS werden nicht unterstützt, bei GitHub wie bei GitLab. Liegt im verknüpften Ordner ein Submodul oder nutzt eine .gitattributes im Ordner oder in einem Ordner darüber filter=lfs, baut gooddeploy nichts; der Status am Commit zeigt einen Fehler mit der betroffenen Datei. Submodule oder LFS in anderen Ordnern des Repos stören nicht, wenn du mit --root einen Ordner ohne sie verknüpfst.

Builds überspringen

Nicht jeder Push braucht einen neuen Build, zum Beispiel wenn sich nur die Doku geändert hat. Dafür gibt es zwei Wege:

Ordner und Dateien ausnehmen. Ändert ein Push nur Dateien, die zu einem der Muster passen, baut gooddeploy nicht:

gooddeploy git link gooddev/shop --skip-paths "docs/**,**/*.md"

Im Dashboard steht dasselbe im Reiter Einstellungen unter „Ändern“ bei Git-Repository im Feld Nicht bauen bei Änderungen nur in …. Die Muster schreibst du wie Pfadfilter (siehe Monorepos): relativ zum Repo, * für beliebige Zeichen in einem Ordnernamen, ** für beliebig viele Ordner. *.md passt deshalb nur auf Dateien in der obersten Ebene des Repos (README.md), **/*.md auf alle Markdown-Dateien. Ändert der Push zusätzlich auch nur eine andere Datei, baut er wie gewohnt. Bei einem Monorepo gelten zuerst die Pfadfilter, danach die Ausnahmen: Ein Push, der dein Projekt gar nicht betrifft, bleibt wie bisher ohne Status. Bei einem neuen Branch oder einem Force-Push kennt gooddeploy die geänderten Dateien nicht vollständig und baut. Die Muster gehören zur Verknüpfung, nicht in gooddeploy.json, und haben nichts mit .gooddeployignore zu tun (die regelt, welche Dateien beim Upload mitgehen).

Hinweis in der Commit-Nachricht. Steht in der Nachricht des neuesten Commits eines Pushes [skip deploy], [deploy skip], [skip ci] oder [ci skip] (Groß- und Kleinschreibung egal), baut gooddeploy nicht. [skip ci] überspringt dabei auch GitHub Actions bzw. GitLab CI; willst du nur gooddeploy überspringen, nimm [skip deploy].

git commit -m "docs: Tippfehler in der Anleitung [skip deploy]"

In beiden Fällen entsteht kein Deployment, und am Commit steht der Status gooddeploy/preview als Erfolg mit „Übersprungen: nur ausgeschlossene Pfade“ bzw. „Übersprungen: [skip deploy] in der Commit-Nachricht“, also grün statt rot. Ein übersprungener Push auf den Produktions-Branch ändert die Live-Version nicht. Baut gerade noch ein früherer Commit und ändert der übersprungene Push nur ausgenommene Dateien, geht der frühere Build trotzdem live. „Jetzt bauen“ baut immer, auch wenn der Commit einen Hinweis trägt. Kommt später: übersprungene Pushes auch in gooddeploy ls und in der Liste der Deployments im Dashboard.

Automatisch live über den Produktions-Branch

Ein Push auf den Produktions-Branch (zum Beispiel der Merge eines Pull Requests nach main) baut wie jeder Push eine Preview. Ist sie fertig und sind alle Pflicht-Checks grün, schaltet gooddeploy sie automatisch live, genau wie gooddeploy promote es tun würde: mit denselben Prüfungen und derselben Prüfung nach dem Umschalten (bei Fehlern automatisch zurück). Im Verlauf von gooddeploy status steht dann git als Auslöser.

Am Commit erscheint dazu der Status gooddeploy/production (im Monorepo gooddeploy/production/<projekt>):

Zwei schnelle Pushes: Es geht nur der neueste Commit des Branches live. Ein älterer Commit, dessen Preview später fertig wird, überholt nie einen neueren; er bleibt als Preview erreichbar. Ein Commit, der nach einem Force-Push nicht mehr auf dem Branch liegt, geht nie automatisch live. Im Monorepo zählt ein neuerer Commit nur, wenn er dein Projekt betrifft (Pfadfilter).

Alles aus dem Produktions-Branch, das nicht automatisch live geht, kannst du jederzeit selbst live schalten: gooddeploy promote <id>.

Live geht nur der Produktions-Branch

Live geht nur, was im Hauptbranch liegt. Keine versehentlichen Deploys halbfertiger Stände.

Hauptbranch heißt hier: der Produktions-Branch, den du beim Verknüpfen eingestellt hast (Standard main). Bei einem verknüpften Projekt gilt:

• Previews anderer Branches (Pull Requests, „Jetzt bauen“ auf einem anderen Branch) kannst du ansehen und teilen, aber nicht live schalten. Im Dashboard steht statt „Live schalten“ der Hinweis „Live geht nur main – erst mergen“; in der Liste der Deployments „Live nur über main“.
• gooddeploy deploy legt weiter eine Preview an, zum Ansehen. Live geht sie nicht, denn den Branch deines lokalen Stands kann gooddeploy nicht prüfen. Live geht es über einen Push bzw. Merge nach main, oder du baust main mit gooddeploy git build.
• gooddeploy promote lehnt solche Previews mit PROMOTE_NOT_PRODUCTION_BRANCH ab (Exit-Code 5), mit dem Hinweis, was zu tun ist. Dasselbe gilt in der API (POST /v1/deployments/{id}/promote, 409).
• Zurückschalten geht weiter: gooddeploy rollback und „Wieder live schalten“ einer früheren Live-Version sind nicht betroffen, auch nicht für Versionen, die vor der Verknüpfung live waren.
• Previews, die vor dem Update der Plattform auf Version 0.1.0-alpha.8 entstanden sind, gelten als „Herkunft unbekannt“ und gehen nicht live; baue den Branch neu („Jetzt bauen“ bzw. gooddeploy git build).

Musst du im Notfall etwas live bringen, das nicht in main liegt: committe den Fix nach main, oder stelle den Produktions-Branch vorübergehend auf deinen Branch um (im Reiter Einstellungen bzw. mit gooddeploy git link <owner/repo> --production-branch <branch>; git link setzt dabei alle übrigen Angaben neu) und baue ihn mit „Jetzt bauen“. Projekte ohne Git-Anbindung sind nicht betroffen: Dort kann jede Preview live.

In der API nennt jedes Deployment seine Herkunft (origin: git oder upload) und, wenn es nicht live darf, promoteBlocked mit Code, Meldung, Hinweis und productionBranch.

Nur Preview, live per Klick

Soll ein Push auf den Produktions-Branch nicht von selbst live gehen, schalte das je Projekt ab: im Dashboard unter Push auf den Produktions-Branch „Nur Preview bauen, live per Klick“ (beim Anlegen oder im Reiter Einstellungen), in der CLI mit gooddeploy git link <owner/repo> --auto-promote=false. Das passt zum Beispiel, wenn du als Agentur deinem Kunden erst die Preview zeigst und erst nach seiner Freigabe live schaltest.

Ein Push auf den Produktions-Branch baut dann wie gewohnt die Preview und prüft sie (Build, Health, Smoke). Live bleibt die bisherige Version. Am Commit steht „Wartet auf Freigabe: live schalten mit gooddeploy promote <id>“. Live schaltest du mit dem Knopf „Live schalten“ auf der Seite des Deployments oder mit gooddeploy promote <id>. Tust du das innerhalb von 2 Stunden nach dem Push, springt der Status am Commit auf „Live“; danach bleibt „Wartet auf Freigabe“ am Commit stehen, auch wenn du später live schaltest.

Das ist etwas anderes als die Sperre nach einem Rollback (unten): Die Sperre setzt gooddeploy von selbst und hebt sie mit dem nächsten gooddeploy promote wieder auf. „Nur Preview“ hast du bewusst eingestellt; es bleibt, bis du es wieder auf „Automatisch live schalten“ stellst (--auto-promote=true).

Gesperrt nach einem Rollback

Nach einem Rollback (von Hand oder automatisch) gehen Pushes auf den Produktions-Branch nicht mehr automatisch live. Sonst würde der nächste Push genau das wieder live schalten, was du gerade zurückgenommen hast. Die Previews werden weiter gebaut; am Commit steht „Gesperrt nach Rollback: live schalten mit gooddeploy promote <id>“, und gooddeploy status zeigt:

  Auto-Promote  gesperrt seit Rollback · Pushes auf main gehen nicht live, bis jemand wieder promotet: gooddeploy promote

Sobald jemand wieder gooddeploy promote ausführt, ist die Sperre aufgehoben und der nächste Push geht wieder automatisch live. In der API steht die Sperre als autoPromoteLocked in GET /v1/projects/{project}/status.

Fremde CI-Ergebnisse am Commit (zum Beispiel GitHub Actions) wartet gooddeploy nicht ab. Sollen deine Tests vor dem Live-Schalten grün sein, trage sie als Pflicht-Check in gooddeploy.json ein und melde das Ergebnis aus der CI mit gooddeploy checks report (Checks). Live nur bei Tags oder Releases kommt später.

Monorepos

Liegen mehrere Apps in einem Repo, verknüpfst du jedes Projekt mit demselben Repo und gibst den Ordner an:

gooddeploy git link gooddev/plattform --root apps/web --project web
gooddeploy git link gooddev/plattform --root apps/admin --paths "apps/admin/**,packages/**" --project admin

• --root ist der Ordner der App im Repo (wie deploy --dir).
• --paths sind Pfadfilter, durch Komma getrennt: Nur Pushes, die eine dieser Dateien ändern, sollen das Projekt bauen. Ohne Angabe gilt <root>/**. Geteilte Ordner wie packages/** gibst du zusätzlich an.
• Mit --root oder --paths heißt der Status am Commit gooddeploy/preview/<projekt> bzw. gooddeploy/production/<projekt> (z. B. gooddeploy/preview/web), damit sich die Projekte eines Repos nicht gegenseitig überschreiben. Der Name wird beim Verknüpfen festgelegt; ohne Wurzelordner und Filter bleibt es gooddeploy/preview. Nutzt du den Status als Pflicht-Check in GitHub oder GitLab, trage diesen Namen ein.

Trennen

gooddeploy git unlink

trennt das Projekt vom Repo (Recht settings); bei GitLab löscht gooddeploy den Webhook. Laufende Deployments bleiben.

gooddeploy git disconnect

trennt eine ganze Verbindung (nur owner und admin, mit Rückfrage; in Skripten --yes). Im Dashboard geht das unter Einstellungen → „Git-Verbindungen“ → „Trennen“; die Rückfrage nennt die verknüpften Projekte. Bei GitHub heißt das: Die gooddeploy-App wird für das ganze Konto bzw. die ganze Organisation deinstalliert, auch für andere Teams, die sie über dieselbe Installation nutzen wollten. gooddeploy trennt dabei alle verknüpften Projekte, nimmt den Zugriff beim Anbieter zurück (GitHub: App deinstalliert; GitLab: Zugriff widerrufen) und löscht die gespeicherten Zugangsdaten. Hat das Team mehrere Verbindungen, nenne die ID: gooddeploy git disconnect gcn_…. Klappt die Rücknahme beim Anbieter nicht, trennt gooddeploy trotzdem alles bei sich und sagt dir, wo du den Zugriff selbst entfernst.

Sicherheit

• gooddeploy speichert keine GitHub-Tokens; für GitLab nur verschlüsselt. Tokens erscheinen nie in Ausgaben oder Logs.
• Die Bestätigungsseite zeigt immer Team und Person. So kann dir niemand über einen fremden Link ein Konto in sein Team „unterschieben“.
• Eine GitHub-Installation verbinden darf nur, wem das Konto gehört: bei einem persönlichen Konto du selbst, bei einer Organisation ein owner der Organisation. Leserecht in der Organisation reicht nicht (GIT_PERMISSION_MISSING). Meldet gooddeploy „Die GitHub-App braucht die Organisationsberechtigung Members: read“, fehlt der App auf der Plattform eine Berechtigung; dann sag goodDEV Bescheid.

Mit der API

Alle Befehle sind Aufrufe der öffentlichen API, die du auch selbst nutzen kannst (Skripte und CI): POST /v1/git/connections, GET /v1/git/connect-requests/{requestId}, GET /v1/git/connections, DELETE /v1/git/connections/{connectionId}, GET /v1/git/connections/{connectionId}/repositories, GET /v1/git/connections/{connectionId}/branches?repository=<owner/repo> (Branches eines Repos mit Standard-Branch, Recht settings) und GET/PUT/DELETE /v1/projects/{project}/git. Die Regel steht dort in previewMode (production-and-requests, all, list) und previewBranches, automatisch live schalten in autoPromote (true oder false; ohne Angabe beim PUT bleibt der bisherige Wert, bei einer neuen Verknüpfung true); GET nennt in branches die festen Branch-Adressen. Einen Freigabelink für eine Branch-Adresse erzeugt POST /v1/projects/{project}/share mit branch oder address (Recht deploy).

„Jetzt bauen“ ist POST /v1/projects/{project}/git/builds (Recht deploy), optional mit {"branch": "feature/login"}; ohne Angabe baut es den Produktions-Branch. Die Antwort (202) nennt Branch und Commit (commitSha); das Deployment erscheint kurz danach in GET /v1/projects/{project}/deployments. Fehler: NOT_FOUND (Projekt nicht verknüpft oder Branch gibt es nicht, zum Beispiel bei einem leeren Repo), GIT_CONNECTION_BROKEN (Git-Konto neu verbinden), PROJECT_LOCKED.