Umgebungsvariablen

Bietet ein Server die Verwaltung der Variablen noch nicht an, enden die Befehle gooddeploy env … mit „noch nicht verfügbar“ (Exit-Code 6); dann richtet goodDEV Variablen für dich ein.

Überblick

gooddeploy env ls                               # Variablen anzeigen, Werte maskiert
gooddeploy env add DATABASE_URL --production    # Wert verdeckt eingeben
gooddeploy env rm DATABASE_URL --production     # Variable löschen
gooddeploy env pull                             # Werte der Previews nach .env.local
gooddeploy env import .env.vercel --production  # alle Variablen aus einer Datei übernehmen

Jede Variable gilt für eine Umgebung: Previews oder Live (Produktion). Die Schalter sind bei allen Unterbefehlen gleich:

Gibt es das Projekt noch nicht, fragen env add und env import wie link und deploy, ob sie es anlegen sollen (danach auch „Postgres anlegen?“), und verknüpfen den Ordner. Ohne Terminal legen sie es nur mit --yes an, sonst enden sie mit Exit-Code 1.

Namen bestehen aus Großbuchstaben, Ziffern und _ und beginnen nicht mit einer Ziffer, z. B. DATABASE_URL oder NEXT_PUBLIC_SITE_URL.

Variablen anzeigen: env ls

gooddeploy env ls

Variablen kunde-website
  NAME                  UMGEBUNG  ART       WERT    GEÄNDERT
  DATABASE_URL          Live      Laufzeit  ••••••  vor 30 min · Bernd
  NEXT_PUBLIC_SITE_URL  Previews  Build     ••••••  vor 2 h · Bernd

Werte zeigt gooddeploy nie an, auch nicht mit --json. Mit --preview oder --production siehst du nur eine Umgebung. gooddeploy env ohne Unterbefehl macht dasselbe wie env ls.

Variablen setzen: env add

gooddeploy env add DATABASE_URL --production
? Wert für DATABASE_URL (Eingabe verdeckt):

Den Wert gibst du nie als Argument an, denn er stünde sonst in der Shell-Historie. Im Terminal fragt gooddeploy verdeckt danach; in Skripten liest es den Wert von der Standardeingabe (ein abschließender Zeilenumbruch fällt weg; mehrzeilige Werte unterstützt gooddeploy noch nicht, speichere sie z. B. Base64-kodiert in einer Zeile):

printf '%s' "$DATABASE_URL" | gooddeploy env add DATABASE_URL --production

gooddeploy env add NAME wert oder NAME=wert endet mit Exit-Code 1 und diesem Hinweis. Eine geänderte Variable wirkt mit dem nächsten Deployment.

Vorsicht bei NEXT_PUBLIC_

Next.js baut Variablen mit NEXT_PUBLIC_ in das JavaScript für den Browser ein; jeder Besucher kann sie lesen. Klingt der Name nach einem Geheimnis (SECRET, TOKEN, PASSWORD, API_KEY …), warnt gooddeploy mit ⚠. Ohne --build erinnert es außerdem daran, dass solche Variablen beim Build gebraucht werden.

Sofort anwenden mit --apply

Mit --apply erzeugt gooddeploy für eine Laufzeit-Variable sofort ein neues Deployment aus demselben Image, ohne neuen Build, und zeigt den Fortschritt bis „bereit“. Das dauert Sekunden statt Minuten.

• Bei --preview (Standard) ist danach die neue Preview bereit. Sie geht nicht live; das sagt gooddeploy auch dazu. Für Live brauchst du --production.
• Bei --production fragt gooddeploy „Jetzt live schalten? (J/n)“ und schaltet wie promote um. Mit --yes ohne Rückfrage; ohne Terminal und ohne --yes schaltet es nicht um und nennt mit ⚠ den Befehl gooddeploy promote <id> --yes.

✓ Laufzeit-Variable GREETING für kunde-website (Live) gesetzt
  Neues Deployment b0wgcvqv aus demselben Image, ohne Build.
  Es geht live, sobald es bereit ist.
✓ Start 1,3 s
✓ Health-Check 0,1 s
✓ b0wgcvqv bereit nach 2,1 s · https://kunde-website--b0wgcvqv.…
✓ Umschalten 1,6 s
✓ live nach 2,1 s: b0wgcvqv

Hast du eben erst live geschaltet und prüft gooddeploy die neue Version noch (etwa eine Minute nach promote), wartet --apply diese Prüfung ab („Warte, bis … geprüft ist“) und schaltet danach um. Wurde die Version in der Zwischenzeit automatisch zurückgerollt, bleibt das neue Deployment eine Preview, und gooddeploy sagt das mit ⚠.

Entsteht kein neues Deployment, meldet gooddeploy das mit ⚠ und dem Grund, z. B. „In Live läuft noch kein Deployment“ oder bei statischen Seiten, die keine Laufzeit-Variablen haben. Die Variable ist trotzdem gespeichert und wirkt mit dem nächsten Deployment.

Build-Variablen brauchen immer einen neuen Build: --build --apply endet mit Exit-Code 1.

Umzug von Vercel: env import

Mit env import übernimmst du alle Variablen eines Projekts auf einmal, z. B. von Vercel. Den ganzen Umzug mit Datenbank und Domain beschreibt Umzug von Vercel. Hol sie dir dort zuerst mit der Vercel-CLI in eine Datei, je Umgebung:

vercel env pull --environment=production .env.vercel
gooddeploy env import .env.vercel --production

  Aus .env.vercel nach kunde-website (Live), nur Namen:
  API_URL:              neu
  STRIPE_SECRET_KEY:    neu
  NEXT_PUBLIC_SITE_URL: neu, Build-Variable
  DATABASE_URL:         übersprungen: setzt gooddeploy für die eigene Datenbank; eine externe einzeln mit gooddeploy env add DATABASE_URL
  VERCEL_OIDC_TOKEN:    übersprungen: Variable von Vercel
? 3 Variable(n) in kunde-website setzen? (J/n)
✓ 3 Variable(n) aus .env.vercel in kunde-website gesetzt

gooddeploy zeigt nur die Namen, nie die Werte, und fragt, bevor es etwas setzt. Für die Previews wiederholst du das mit vercel env pull --environment=preview und --preview (Standard), am besten in eine neue Datei: Eine vorhandene Datei ergänzt vercel env pull nur, Variablen der anderen Umgebung blieben darin stehen. Werte vom Typ „Secret“ gibt Vercel nicht heraus; prüf die Datei vor dem Import und setz solche Variablen einzeln mit env add (siehe Umzug von Vercel). Danach gooddeploy deploy, oder gleich --apply (siehe oben). Lösch die Datei anschließend, sie enthält deine Geheimnisse: rm .env.vercel.

Die Datei hat das übliche .env-Format: NAME=wert je Zeile, Kommentare mit #, Werte auch in "…" (mit \n für Zeilenumbrüche) oder '…', optional mit export davor. Kommt ein Name doppelt vor, gilt der letzte Wert.

Übersprungen werden mit Hinweis: Namen, die gooddeploy selbst setzt (PORT, NODE_ENV, HOSTNAME, GOODDEPLOY_… und andere), DATABASE_URL und DATABASE_URL_UNPOOLED (gooddeploy setzt sie für die eigene Datenbank; behältst du eine externe Datenbank, setz sie einzeln mit env add), Variablen von Vercel (VERCEL, VERCEL_…, TURBO_…), leere und mehrzeilige Werte sowie ungültige Namen.

Gibt es eine Variable schon, fragt gooddeploy „Überschreiben? [j/N]“; ohne Terminal bleibt sie, wie sie ist, außer mit --overwrite.

Variablen löschen: env rm

gooddeploy env rm DATABASE_URL --production

Die Variable verschwindet mit dem nächsten Deployment. Gibt es sie in der gewählten Umgebung nicht, endet env rm mit NOT_FOUND (Exit-Code 1).

Werte lokal nutzen: env pull

gooddeploy env pull                # Previews
gooddeploy env pull --production   # Live

env pull schreibt die Werte einer Umgebung in die Datei .env.local im aktuellen Ordner, so wie Next.js sie liest (NAME="wert", Zeilenumbrüche als \n). Die Datei ist nur für dich lesbar. Ist sie nicht von git ignoriert, warnt gooddeploy: Trag dann .env*.local in deine .gitignore ein.

Eine vorhandene .env.local überschreibt env pull nur nach Rückfrage bzw. mit --yes. Mit --json stehen im Ergebnis nur die Namen, nie die Werte.

Rechte

env ls braucht read, env add, env import und env rm brauchen deploy, env pull und inspect --values brauchen read:sensitive, weil sie die Werte herausgeben (siehe Rechte).

Geheimnisse in Ausgaben

gooddeploy schreibt Werte nie in seine Ausgabe, außer du verlangst sie ausdrücklich mit gooddeploy inspect --values (Recht read:sensitive; dann im Klartext, auch mit --json – nicht in CI-Logs verwenden). Nennt eine Fehlermeldung der Plattform den gerade eingegebenen Wert, ersetzt gooddeploy ihn durch [maskiert], sobald er mindestens 6 Zeichen hat. Die Plattform selbst maskiert bekannte Werte in Build-Logs und Meldungen ebenso.