Codex-Deployment: End-to-End-Workflow mit Dockup

Ein Codex-Deployment sollte mit Belegen enden, nicht mit einer Vermutung. Die praktische Herausforderung besteht nicht darin, Codex zum Ausführen eines Deployment-Befehls aufzufordern, sondern dem Agenten eine Schnittstelle bereitzustellen, die das exakte Ziel identifiziert, auf einen finalen Status wartet, echte Exit-Codes zurückgibt und Fehlerdetails ohne Browser zugänglich macht.

Dockup ist die Deployment-Ebene für diesen Workflow. Die CLI liefert Codex für jeden unterstützten Befehl strukturiertes JSON, und der enthaltene Skill zeigt dem Agenten, wie er sich authentifiziert, Services findet, Deployments ausführt, Diagnosen erstellt und vor destruktiven Aktionen stoppt.

Wie installierst du den Codex-CLI-Skill?

Installiere die CLI global und führe anschließend den einzigen Installer für den Skill aus. Er schreibt den kanonischen Skill und verknüpft ihn sowohl mit Claude Code als auch mit Codex:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

Der kanonische Skill befindet sich unter ~/.agents/skills/dockup/ und ist mit ~/.codex/skills/ verknüpft. Er wird mit dockup-cli ausgeliefert, sodass ein normales Update sowohl die ausführbare Datei als auch die zugehörigen Anweisungen aktualisiert:

dockup update

Diese Versionskopplung ist bei einer großen Befehlsoberfläche wichtig. Ein Agent sollte niemals ein gemerktes Flag ausführen, nur weil es in einem alten Prompt vorkam. Codex sollte den mitgelieferten Skill und die aktuelle Dockup-CLI-Referenz als maßgebliche Quelle für Befehle verwenden.

Die Designüberlegungen hinter Skills findest du unter Agent-Skills vs. MCP.

Wie authentifiziert sich Codex ohne interaktives Terminal?

Eine Sandbox oder ein CI-Job kann möglicherweise keinen browserbasierten Login abschließen. Setze ein Token in der Prozessumgebung:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

DOCKUP_TOKEN hat Vorrang vor der lokalen Konfigurationsdatei. Die whoami-Antwort zeigt an, ob die aktive Berechtigung aus der Umgebung oder aus der Konfiguration stammt. Das hilft Codex bei der Diagnose des häufigen Falls, dass ein veraltetes lokales Token und ein CI-Token gleichzeitig vorhanden sind.

Behandle das Token als Infrastruktur-Secret. Hinterlege es nicht in AGENTS.md, SKILL.md, der Versionsverwaltung, in fest im Repository gespeicherten Befehlsbeispielen oder im abschließenden Transkript des Agenten. Verwende in CI den verschlüsselten Secret-Speicher der Plattform und stelle den Wert nur dem Deployment-Schritt zur Verfügung. Das vollständige Muster für nicht interaktive Abläufe wird unter CI/CD mit DOCKUP_TOKEN beschrieben.

Lege vor der Erteilung von Schreibzugriffen an Codex den Berechtigungsumfang fest. Ein sinnvoller anfänglicher Umfang umfasst die Service-Suche, Deployments, das Lesen von Logs und Statusprüfungen. Das Löschen von Datenbanken, die Zerstörung von Services, Teamänderungen und das Bereinigen von Konfigurationen sollten weiterhin eine Freigabe erfordern.

Wie findet oder erstellt Codex den richtigen Service?

Mache die Suche zum ersten Vorgang. Fordere Codex nicht dazu auf, „Payments API“ in einen geratenen Slug umzuwandeln:

dockup services --json

Jedes Ergebnis enthält ein exaktes target im Format project/service. Codex sollte diesen Wert in nachfolgenden Befehlen übernehmen und in seiner Zusammenfassung ausgeben.

Wenn kein Service vorhanden ist, erstelle einen aus Git:

dockup create payments-api \
  --repo https://github.com/acme/payments-api \
  --project production \
  --branch main \
  --deploy \
  --wait \
  --link \
  --json

Der Befehl erstellt den Service, führt das Deployment aus, wartet, bis das Deployment abgeschlossen ist, und legt eine .dockup-Verknüpfung im Arbeitsverzeichnis an. Wenn eine Dockerfile vorhanden ist, wird sie verwendet; andernfalls übernimmt Nixpacks die automatische Build-Erkennung.

Wenn Codex seinen Session-Status verliert oder ein Workflow nach einer Netzwerkunterbrechung erneut ausgeführt wird, sollte Codex die Services erneut suchen und das exakte Ziel prüfen, bevor Änderungen vorgenommen werden. Wenn das Ziel bereits existiert, sollte Codex anhand des Status und der Deployment-Historie fortfahren, statt eine weitere Create-Anfrage zu senden.

Die vollständige, repositorybasierte Abfolge findest du unter Vom Git-Repository zur Produktion.

Wie sollte Codex die Konfiguration vor dem Deployment vorbereiten?

Fordere Codex dazu auf, die aktuellen Service-Metadaten zu prüfen, bevor Änderungen vorgenommen werden:

dockup info production/payments-api --json
dockup env list -s production/payments-api --json

Die Umgebungsantwort enthält die Schlüssel und isSecret-Markierungen, während Secret-Werte maskiert bleiben. Codex kann gewöhnliche Variablen und Secrets getrennt hinzufügen:

dockup env set NODE_ENV=production \
  -s production/payments-api \
  --json

dockup env set STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY" \
  --secret \
  -s production/payments-api \
  --json

Hinterlege niemals ein Production-Secret in dockup.yaml; das Manifest eignet sich für überprüfbare Konfigurationen im Klartext, nicht für Zugangsdaten. Vorhandene Secret-Variablen werden durch den Config-as-Code-Workflow weder überschrieben noch entfernt.

Konfiguriere den Port, an dem der Service Verbindungen annimmt, sowie den Readiness-Check, sobald diese Werte bekannt sind:

dockup set production/payments-api --port 3000 --json
dockup health production/payments-api \
  --path /health \
  --interval 5 \
  --retries 5 \
  --json

Ein Readiness-Gate macht die Produktionsverifizierung aussagekräftig. Die Plattform führt ein Blue-Green-Deployment aus und leitet den Traffic erst weiter, wenn die neue Version das Gate erfüllt.

Wie bestätigt die Produktionsverifizierung den finalen Status?

Für einen bestehenden Service genügt ein Befehl:

dockup deploy production/payments-api \
  --wait \
  --timeout 900 \
  --json

Das explizite Timeout entspricht dem Standardwert von 900 Sekunden und macht die Absicht des Workflows sichtbar. Exit 0 bedeutet, dass das Deployment erfolgreich war. Ein Ergebnis ungleich null mit deploy_failed bedeutet, dass Build oder Deployment fehlgeschlagen sind. deploy_timeout bedeutet, dass der Vorgang nach Ablauf der Wartezeit noch keinen finalen Status erreicht hatte.

Die korrekte Verzweigungslogik für Codex basiert auf dem Prozessstatus:

Ergebnis	Aktion von Codex
Exit 0, status:"success"	Mit Health-, Uptime- und Security-Verifizierung fortfahren
deploy_failed	Build-Logs lesen und den ersten umsetzbaren Fehler identifizieren
deploy_timeout	Unsicherheit melden; Status prüfen oder mit begründetem Timeout erneut versuchen
not_logged_in	Stoppen und ein gültiges Token anfordern
needs_confirm	Stoppen und eine menschliche Freigabe anfordern

Nach einem erfolgreichen Codex-Deployment sollten beobachtbare Belege gesammelt werden:

dockup status production/payments-api --json
dockup uptime production/payments-api --hours 24 --json
dockup security production/payments-api --json

Uptime-Prüfungen werden minütlich ausgeführt und enthalten Statistiken zur Antwortzeit, etwa p95. Security-Ergebnisse enthalten Image-CVEs und Konfigurationsprüfungen. Diese Signale beweisen nicht, dass die Anwendung fachlich korrekt funktioniert. Codex sollte daher zusätzlich die Smoke Tests des Repositorys ausführen, sofern diese verfügbar sind.

Wie sollte Codex ein fehlgeschlagenes Release diagnostizieren und wiederherstellen?

Build-Fehler und Laufzeitfehler erfordern unterschiedliche Logs. Verwende die neuesten Build-Ausgaben, wenn das Deployment nie einen ausführbaren Container erreicht hat:

dockup logs production/payments-api --build --json

Verwende Runtime-Logs, wenn das Image erstellt wurde, die Anwendung aber abstürzt, den falschen Port verwendet oder nach dem Start fehlschlägt:

dockup logs production/payments-api --json

Der Follow-Modus ist während eines langen Builds hilfreich:

dockup logs production/payments-api --build -f --json

Im JSON-Modus wird die Follow-Ausgabe als NDJSON ausgegeben, sodass Codex jedes Batch verarbeiten kann, sobald es eintrifft. Der Stream endet bei einem finalen Deployment-Status und bewahrt den tatsächlichen Fehler-Exit-Code.

Die Wiederherstellung beginnt mit der Historie, nicht mit einem geratenen Rollback-Ziel:

dockup deployments production/payments-api -n 20 --json
dockup rollback <deploymentId> production/payments-api --json

Codex sollte ein nachweislich erfolgreiches Deployment identifizieren, die ausgewählte ID nennen und die Fehlerbelege sichern, bevor es dieses erneut ausführt. Es sollte niemals ohne Prüfung von Status und Zeitstempeln „das zweite Element“ auswählen.

Ein nützlicher Abschlussbericht enthält sieben Felder: Ziel, Branch oder Commit, Deployment-ID, Exit-Code, finaler Status, Produktions-URL und Folgeaktionen. Dieses Format macht jedes Codex-Deployment für eine Person oder einen späteren Automatisierungsschritt überprüfbar.

Ein kompaktes Verifizierungsskript

Dieses Shell-Muster hält Deployment und Diagnose in einem transparenten Kontrollfluss:

if dockup deploy production/payments-api --wait --json > deploy-result.json; then
  dockup status production/payments-api --json
  dockup uptime production/payments-api --hours 24 --json
else
  dockup logs production/payments-api --build --json
  exit 1
fi

Das Skript sucht nicht per grep nach einem Erfolgssatz. Es vertraut auf den Exit-Code der CLI, bewahrt das Deployment-JSON und schlägt im aufrufenden Job fehl, wenn die Produktion keinen erfolgreichen Status erreicht hat.

Mache Wiederholungen beobachtbar statt unsichtbar

Agent-Sessions können unterbrochen werden, nachdem ein Vorgang gestartet wurde, aber bevor das Ergebnis das Transkript erreicht. Der nächste Codex-Lauf sollte nicht blind jede Änderung wiederholen. Er sollte den Service erneut suchen, das neueste Deployment prüfen und feststellen, ob der vorherige Vorgang einen finalen Status erreicht hat.

Ein Codex-Deployment-Runbook sollte Befehle danach klassifizieren, ob sie sicher wiederholt werden können, erst nach einer Prüfung wiederholt werden dürfen oder eine Freigabe erfordern. Lesevorgänge können sicher wiederholt werden. Die Erstellung eines Services erfordert zunächst eine Suche. Ein neues Deployment ist ein neues Produktionsereignis und sollte als solches protokolliert werden. Bereinigungen und andere destruktive Vorgänge bleiben Entscheidungen des Menschen.

Plattformverifizierung und Anwendungsverifizierung trennen

Dockup kann belegen, dass ein Build abgeschlossen wurde, der Container bereit war und minütliche Prüfungen den öffentlichen Service erreichen. Codex sollte dennoch anwendungsspezifische Prüfungen ausführen: einen öffentlichen Health-Endpunkt, eine authentifizierte Testanfrage oder einen vom Repository bereitgestellten Smoke Test, der keine Kundendaten verändert.

Das Endergebnis sollte beide Ebenen nennen. „Plattform-Deployment erfolgreich“ und „Application-Smoke-Test bestanden“ sind unterschiedliche Aussagen. Wenn nur die erste Aussage verfügbar ist, sollte Codex das klar benennen, statt die Unsicherheit in ein grünes Häkchen zu verdichten.

Prüfe vor der Automatisierung die installierte Befehlsoberfläche

Eine wiederverwendbare Codex-Aufgabe sollte mit der Prüfung von dockup skill status --json beginnen und die aktuelle CLI-Referenz öffnen, wenn sie von einer weniger vertrauten Option abhängt. So wird verhindert, dass eine Session einem Beispiel folgt, das für ein anderes Release geschrieben wurde.

Diese Prüfung ist besonders in kurzlebigen Runnern nützlich, in denen sich eine frische globale npm-Installation von der Installation auf dem Laptop eines Entwicklers unterscheiden kann. Codex kann den Status des Skills melden, bevor es den ersten Schreibvorgang in der Produktion ausführt, und macht den Deployment-Eintrag dadurch reproduzierbar.

Abschließende Übergabe

Bewahre die Belege auf.

Mache das Ziel sichtbar

Gib das exakte Service-Ziel im Abschlussbericht aus.

Halte die Entscheidung zur Quelle fest

Dokumentiere, ob Dockup die Dockerfile des Repositorys oder Nixpacks verwendet hat. Diese Information hilft der nächsten Codex-Session, das passende Build-Log auszuwählen, und verhindert, dass eine Änderung der Quellstruktur mit einem Plattformvorfall verwechselt wird.

Dokumentiere außerdem, ob das automatische Deployment bei einem Push aktiviert ist. Andernfalls können sich ein manuelles Agent-Release und ein durch einen Push ausgelöstes Release überschneiden und aus derselben Untersuchung zwei Produktionsereignisse erzeugen.

Überführe den Workflow in die Produktion

Führe das erste Codex-Deployment für einen kurzlebigen oder risikoarmen Service aus und übertrage anschließend denselben verifizierten Befehlsvertrag in die Produktion.

npm install -g dockup-cli
dockup skill install

Der erste Befehl installiert die CLI. Der zweite installiert den passenden Dockup-Skill für Claude Code und Codex. Starte kostenlos unter app.dockup.ai.

FAQ

Kann Codex ein neues Git-Repository mit einem Befehl deployen?

Ja. dockup create kann den Service erstellen, ihn deployen, auf das finale Ergebnis warten und das aktuelle Verzeichnis verknüpfen, wenn der Befehl mit --deploy, --wait und --link verwendet wird.

Wie sollte sich Codex bei Dockup authentifizieren?

Verwende DOCKUP_TOKEN in der Prozessumgebung und überprüfe es mit dockup whoami --json. So lässt sich der interaktive Browser-Login in Sandboxes und CI vermeiden.

Was beweist, dass ein Codex-Deployment erfolgreich war?

Der Deploy-Befehl muss nach der Ausführung mit --wait mit Exit 0 beendet werden, und sein JSON muss einen erfolgreichen finalen Status melden. Führe anschließend status, uptime und anwendungsspezifische Smoke Checks aus.

Kann Codex Produktions-Secrets aus Dockup auslesen?

Nein. Secret-Werte werden in der Ausgabe maskiert. Codex kann ein Secret setzen oder ersetzen, erhält beim Auflisten der Konfiguration aber nicht den gespeicherten Wert.

Was sollte Codex mit needs_confirm tun?

Codex sollte stoppen und eine ausdrückliche menschliche Freigabe anfordern. Der Fehler zeigt an, dass ein destruktiver Befehl ohne die erforderliche Bestätigung mit --yes versucht wurde.