Erste Schritte – gooddeploy

Neu mit Testzugang? Der kürzeste Weg zur ersten App steht unter Testzugang: deine erste App in 10 Minuten.

Installieren

gooddeploy ist ein einzelnes Programm für macOS und Linux. Installiere es mit:

curl -fsSL https://gooddeploy.de/install.sh | sh

Das Skript lädt die passende Version für dein System, prüft die Prüfsumme und legt gooddeploy nach /usr/local/bin (falls beschreibbar) oder nach ~/.local/bin. Bei Bedarf ergänzt es deinen PATH und richtet die Tab-Vervollständigung für zsh und bash ein.

Ob alles geklappt hat, siehst du mit:

gooddeploy version
gooddeploy help

gooddeploy help zeigt alle Befehle. Die Optionen eines Befehls siehst du mit --help hinter dem Befehl, z. B. gooddeploy deploy --help (oder gooddeploy help deploy). Vertippst du dich bei einem Befehl, schlägt gooddeploy den passenden vor.

Optionen für das Skript (als Umgebungsvariablen vor sh):

Variable	Wirkung
`GOODDEPLOY_INSTALL_DIR`	eigener Zielordner
`GOODDEPLOY_VERSION`	bestimmte Version statt der neuesten
`GOODDEPLOY_NO_MODIFY_PATH=1`	`PATH` nicht ändern
`GOODDEPLOY_NO_COMPLETION=1`	keine Tab-Vervollständigung einrichten

Die Tab-Vervollständigung kannst du auch selbst erzeugen: gooddeploy completion zsh bzw. gooddeploy completion bash gibt das Skript aus.

Anmelden

gooddeploy login

gooddeploy fragt nach deiner E-Mail-Adresse. Hast du dich auf diesem Rechner schon einmal angemeldet, steht die zuletzt benutzte Adresse in Klammern; Enter übernimmt sie.

E-Mail-Adresse [du@agentur.de]:

gooddeploy zeigt dann einen Code wie KXQT-7PRM (im Terminal in einem Kasten) und schickt dir eine E-Mail mit einem Link; während du bestätigst, läuft die Zeit bis zum Ablauf des Codes mit. Betreff und erste Zeile der E-Mail nennen das Team, für das die Anmeldung gilt (z. B. „Anmeldung bei gooddeploy bestätigen – Team goodDEV Projekte“); gehörst du mehreren Teams an und lässt sich kein Team ableiten (siehe Mehrere Teams), steht dort „wählst du auf der Seite“. Öffne den Link, gib dort den Code aus deinem Terminal ein, und gooddeploy meldet dich an, sobald du bestätigt hast. Danach begrüßt dich gooddeploy mit deinem Namen und zeigt, auf welche Projekte du mit welchen Rechten zugreifen darfst. Die Anmeldung gilt eine Weile; wie lange, zeigen login und whoami („Gültig bis …“).

Die Seite zum Bestätigen

Die Seite aus der E-Mail zeigt zuerst und fett das Team, für das du den Zugang freigibst (oder die Auswahl, wenn du es dort wählst), dann wer sich anmelden möchte: deine E-Mail-Adresse, das Gerät (z. B. „gooddeploy CLI 0.0.2 · macOS (arm64)“), die IP-Adresse, den ungefähren Ort und die Uhrzeit der Anfrage. Vergleiche die Angaben mit dem, was du gerade tust.

Datenschutz: Der ungefähre Ort (z. B. „Dresden, Deutschland“) kommt aus der IP-Adresse und ist nur ein Anhaltspunkt: Mobilfunk, VPN oder ein Firmen-Proxy zeigen oft eine andere Stadt oder ein anderes Land. Bei einer Adresse aus einem Heim- oder Firmennetz steht dort „lokal“. gooddeploy schlägt den Ort in einer eigenen Datenbank nach und fragt keinen anderen Dienst; die Daten stammen von DB-IP („IP Geolocation by DB-IP“, https://db-ip.com, Lizenz CC BY 4.0). Den Ort speichert gooddeploy nur im Protokoll der Anmeldung, wie die IP-Adresse.

Bestätige nur, wenn du gerade selbst gooddeploy login gestartet hast. Gib nie einen Code ein, den dir jemand anderes nennt, auch niemand von goodDEV. Wer dir einen Code diktiert, will sich mit deiner Adresse anmelden.

Hast du die Anmeldung nicht gestartet, klick auf Abbrechen. Die Anfrage ist dann verworfen: Der Link und der Code gelten nicht mehr, und im Terminal, das die Anmeldung gestartet hat, erscheint „abgelaufen“. Ohne den Link aus deinem Postfach und den Code aus dem Terminal kommt niemand weiter; eine fremde Anfrage heißt nur, dass jemand deine E-Mail-Adresse kennt.

Mail „Neue Anmeldung bei gooddeploy“

Nach jeder Bestätigung schickt dir gooddeploy eine E-Mail „Neue Anmeldung bei gooddeploy – Team …“ mit dem gewählten Team (im Betreff und fett in der ersten Zeile), Uhrzeit, Gerät, IP-Adresse und ungefährem Ort. Warst du das selbst, ist nichts zu tun. Warst du es nicht, widerrufe den fremden Zugang sofort selbst (siehe Deine Zugänge): gooddeploy tokens zeigt alle deine Zugänge mit Gerät und Zeit, gooddeploy tokens revoke <id> widerruft den fremden. Bist du gerade nicht angemeldet, melde dich zuerst mit gooddeploy login an. Schreib danach an info@gooddev.de, damit wir mit dir prüfen, was passiert ist.

Mit Zugangscode

In der Pilotphase bietet die Plattform den Login per E-Mail noch nicht überall an. Dann sagt login nach der Adresse „Der Login per E-Mail ist … noch nicht verfügbar“ und fragt stattdessen nach deinem Zugangscode, den du von goodDEV bekommst. Den Code fragt gooddeploy verdeckt ab; Leerzeichen beim Abtippen zählen nicht. Der Code wird sofort geprüft. Lässt du die Frage nach der E-Mail leer (ohne Vorschlag), geht es ebenfalls direkt zum Zugangscode.

Die Anmeldung liegt in ~/.config/gooddeploy/auth.json (bzw. unter $XDG_CONFIG_HOME/gooddeploy/). Ordner und Datei sind nur für dich lesbar. Teile diese Datei nicht und lege sie nie in ein Git-Repo.

Wer bin ich, was darf ich?

gooddeploy whoami

In Skripten

Ohne Terminal (z. B. in einem Skript) fragt login nicht nach. Gib dort die Adresse oder den Code mit:

gooddeploy login --email du@agentur.de
gooddeploy login --token <zugangscode>

Ohne beides liest login den Zugangscode aus der ersten Zeile der Standardeingabe; ist sie leer, endet login mit einem Hinweis auf beide Aufrufe (Exit-Code 1). login --email fragt nie nach einem Zugangscode: Bietet die Plattform den Login per E-Mail noch nicht an, endet es mit „noch nicht verfügbar“ (Exit-Code 6). In der CI brauchst du gar kein login: Setze dort GOODDEPLOY_TOKEN (siehe Für Skripte und CI).

Mehrere Teams

Gehörst du mehreren Teams an (z. B. ein Team je Kunde deiner Agentur), gilt jede Anmeldung für genau ein Team. gooddeploy merkt sich aber eine Anmeldung je Team: Meldest du dich für ein zweites Team an, bleibt die erste erhalten, und du wechselst zwischen den Teams, ohne dich neu anzumelden.

gooddeploy login --team "Kunde Süd"
gooddeploy login --team "Agentur Nord"

--team nimmt den Namen (Groß- und Kleinschreibung egal) oder die ID des Teams. Betreff und Seite der E-Mail nennen dann das Team; passt der Name zu keinem deiner Teams, zeigt die Seite die Auswahl. Auch ohne --team schickt login das Team mit, wenn es sich ableiten lässt: aus der Verknüpfung im aktuellen Ordner (siehe unten), sonst das Team, für das du dich zuletzt angemeldet hast. Nur wenn es gar keinen Anhaltspunkt gibt (erste Anmeldung), wählst du das Team auf der Seite.

Welche Teams auf diesem Rechner angemeldet sind, zeigt:

gooddeploy teams

Deine Teams auf diesem Rechner
  TEAM            ROLLE   GÜLTIG BIS
  Agentur Nord    owner   14.01.2027  Standard
  Kunde Süd       member  14.01.2027
Ohne Anmeldung hier: Kunde West – anmelden: gooddeploy login --team <name>
Standardteam wechseln: gooddeploy team use <name>, für einen Befehl: --team <name>

Das Standardteam ist das Team deiner letzten Anmeldung. Wechseln kannst du es mit gooddeploy team use "Kunde Süd". Jeder Befehl nimmt das Team in dieser Reihenfolge:

--team <name> beim Aufruf (z. B. gooddeploy deploy --team "Kunde Süd"),
die Umgebungsvariable GOODDEPLOY_TEAM,
das Team aus .gooddeploy/project.json: link und das erste deploy merken sich dort das Team, mit dem du verknüpft hast. In diesem Ordner arbeitest du danach immer im richtigen Team, egal welches gerade Standard ist (gilt nicht, wenn du mit --project ein anderes Projekt nennst),
sonst das Standardteam.

Bist du für das gewählte Team auf diesem Rechner nicht angemeldet, sagt gooddeploy das und nennt den passenden Befehl, z. B.:

✗ Für das Team Kunde West bist du auf diesem Rechner nicht angemeldet (Team aus --team).
  → Melde dich für das Team an: gooddeploy login --team 'Kunde West' (deine Teams hier: gooddeploy teams)

Das gilt auch für das Team aus .gooddeploy/project.json: Fehlt dafür die Anmeldung, bricht jeder Befehl ab (Exit-Code 3). gooddeploy weicht nie still auf dein Standardteam aus und legt dort nichts an; so landet ein eingecheckter Ordner nicht aus Versehen als neues Projekt im falschen Team. Ist das Projekt inzwischen in ein anderes Team umgezogen, sucht gooddeploy es in deinen Teams und nennt den Befehl zum Umstellen:

✗ Für das Team Kunde West bist du auf diesem Rechner nicht angemeldet (Team aus .gooddeploy/project.json).
  Das Projekt kunde-website gibt es in deinem Team Agentur Nord (umgezogen?). Verknüpfung umstellen:
    → gooddeploy link kunde-website --team 'Agentur Nord'
  → Melde dich für das Team an: gooddeploy login --team 'Kunde West' (deine Teams hier: gooddeploy teams)

Für einen einzelnen Befehl in einem anderen Team nimm --team oder GOODDEPLOY_TEAM.

Läuft die Anmeldung für ein Team ab, nennt die Meldung ebenfalls gooddeploy login --team <name>. Eine Anmeldung aus einer älteren Version von gooddeploy gilt weiter; beim nächsten login übernimmt gooddeploy sie als Anmeldung für ihr Team.

Deine Zugänge

Jede Anmeldung legt einen eigenen Zugang an (90 Tage gültig). Welche Zugänge es für dein Team gibt, zeigt:

gooddeploy tokens

 Deine Zugänge
  ID                             GERÄT                                                   ANGELEGT          ZULETZT BENUTZT  GÜLTIG BIS
  tok_01K7GD0000000000000000CUR  gooddeploy CLI 0.0.2 · macOS (arm64) (diese Anmeldung)  16.10.2026 08:30  vor 1 min        14.01.2027
  tok_01K7GD0000000000000000OLD  gooddeploy CLI 0.0.2 · Linux (amd64)                    12.10.2026 08:30  nie              14.01.2027
Fremdes Gerät? Widerrufen: gooddeploy tokens revoke <id>

gooddeploy tokens ls ist dasselbe. Die Liste zeigt nur deine eigenen, noch gültigen Zugänge im Team deiner Anmeldung (Zugänge in einem anderen Team siehst du mit gooddeploy tokens --team <team>); „diese Anmeldung“ ist der Zugang, mit dem du gerade arbeitest. „Zuletzt benutzt“ ist auf die Minute genau.

Einen Zugang widerrufst du mit seiner ID:

gooddeploy tokens revoke tok_01K7GD0000000000000000OLD

Der Zugang gilt sofort nicht mehr; wer ihn benutzt, bekommt „Nicht angemeldet“. Widerrufst du den Zugang, mit dem du gerade arbeitest, melde dich danach neu an. Zugänge anderer Personen siehst und widerrufst du nicht; eine fremde ID meldet „nicht gefunden“. Zugänge für die CI (GOODDEPLOY_TOKEN) verwaltet goodDEV. Kennt der Server eigene Zugänge noch nicht (feste Zugangscodes aus der Pilotphase), meldet tokens „noch nicht verfügbar“ (Exit-Code 6).

Abmelden

gooddeploy logout

widerruft die Zugänge dieses Rechners auf dem Server und löscht die Anmeldung hier, für alle Teams. Mit gooddeploy logout --team <name> meldest du dich nur von diesem Team ab; die anderen bleiben angemeldet. Die API-Adresse und deine E-Mail-Adresse bleiben in auth.json stehen, damit sich ein späteres gooddeploy login wieder bei derselben Plattform anmeldet und die Adresse vorschlägt.

Kann der Server den Zugang nicht widerrufen, meldet logout dich trotzdem auf diesem Rechner ab und sagt dir, warum der Zugang weiter gilt:

Der Server ist nicht erreichbar: Der Zugang gilt bis zu seinem Ablauf. Widerrufe ihn später mit gooddeploy tokens revoke <id> (nach einem neuen login).
Fester Zugangscode aus der Pilotphase oder ein Server, der Zugänge noch nicht widerrufen kann: Der Code bleibt gültig; wenn er nicht mehr gelten soll, sag goodDEV Bescheid.

Ist GOODDEPLOY_TOKEN gesetzt, weist logout darauf hin, dass Befehle weiter diesen Zugang nutzen; diesen Zugang widerruft logout nicht.

Projekt verknüpfen

Jedes Deploy gehört zu einem Projekt, z. B. kunde-website. Projektnamen haben 3 bis 30 Zeichen, nur Kleinbuchstaben, Ziffern und einzelne Bindestriche.

Am einfachsten verknüpfst du dein Repo einmal mit dem Projekt:

cd mein-repo
gooddeploy link kunde-website

link prüft, ob es das Projekt gibt, und schreibt .gooddeploy/project.json. Danach brauchst du in diesem Repo kein --project mehr. Ohne Namen fragt link im Terminal nach dem Namen und schlägt einen vor (aus dem Feld name in package.json, sonst aus dem Ordnernamen).

gooddeploy bestimmt das Projekt in dieser Reihenfolge:

--project <name> beim Aufruf,
die Umgebungsvariable GOODDEPLOY_PROJECT,
die Datei .gooddeploy/project.json im Repo,
sonst fragt deploy im Terminal nach dem Namen; ohne Terminal gilt der Name deines Repo-Ordners, aber nur, wenn es dieses Projekt schon gibt.

Neues Projekt anlegen

Gibt es das Projekt noch nicht, legt gooddeploy es nicht nebenbei an, sondern fragt im Terminal nach:

? Projektname [kunde-website]:
? Projekt kunde-website gibt es im Team Agentur Nord noch nicht. Jetzt dort anlegen? (J/n)
✓ Projekt kunde-website angelegt
? Postgres anlegen? (J/n)

Enter übernimmt jeweils den Vorschlag. Die Rückfrage nennt das Team, in dem das Projekt entsteht; ein anderes wählst du mit --team. Das geht mit gooddeploy link und beim ersten gooddeploy deploy; zum Anlegen brauchst du das Recht deploy. Ohne Terminal (Skript, CI) legt gooddeploy kein Projekt an: deploy und link enden dann mit NOT_FOUND (Exit-Code 1) und dem Hinweis auf gooddeploy link <name>. In einem Skript legst du ein Projekt ausdrücklich mit gooddeploy link <name> --yes an, mit Postgres per --yes --postgres.

Gut zu wissen: Eine Datenbank lässt sich derzeit nur beim Anlegen einrichten; nachträglich legt sie goodDEV für dich an. Wie deine App sie nutzt, steht unter Datenbank in deiner App nutzen. Bietet ein Server Postgres nicht an, antwortet gooddeploy „Postgres ist auf diesem Server noch nicht verfügbar; das kommt später.“; das Projekt ist trotzdem angelegt.

Die Verknüpfung gehört nicht ins Git

.gooddeploy/project.json ist eine lokale Verknüpfung zwischen deinem Ordner und dem Projekt. Damit sie nicht im Git landet, legt gooddeploy daneben .gooddeploy/.gitignore an; der Ordner ignoriert sich damit selbst, git status bleibt sauber, und deine eigene .gitignore bleibt unberührt. Kolleginnen und Kollegen verknüpfen ihren Checkout selbst mit gooddeploy link.

Liegt dein Projekt in einem Unterordner (z. B. site/), deployst du mit --dir site. Hast du das Repo mit gooddeploy link verknüpft, nimmt deploy --dir site die Verknüpfung aus dem Repo-Root; ein Projekt je Repo ist der Normalfall. Gibt es keine Verknüpfung, landet sie beim ersten Deploy in site/.gooddeploy/project.json, und die gilt dann für site/. Aus site/ heraus funktionieren status, promote und rollback in beiden Fällen ohne --project.

Wie geht es weiter?

Deploy, Preview, Promote, Rollback: deine erste Seite online bringen.
Rechte: was dein Zugangscode darf.