Deployment di Codex: workflow Dockup end-to-end

Un deployment di Codex dovrebbe concludersi con dati concreti, non con un'ipotesi. La difficoltà pratica non consiste nel chiedere a Codex di eseguire un comando di deployment, ma nel fornire all'agent un'interfaccia che identifichi il target esatto, attenda uno stato terminale, restituisca exit code reali ed esponga i dettagli degli errori senza usare un browser.

Dockup è il deployment layer di questo workflow. La sua CLI fornisce a Codex JSON strutturato per ogni comando supportato, mentre la skill inclusa insegna all'agent come autenticarsi, individuare i servizi, eseguire deployment, diagnosticare i problemi e fermarsi prima delle operazioni distruttive.

Come si installa la skill della CLI di Codex?

Installa la CLI globalmente, quindi esegui l'unico installer della skill. Scrive la skill canonica e la collega sia a Claude Code sia a Codex:

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

La skill canonica si trova in ~/.agents/skills/dockup/ ed è collegata tramite symlink a ~/.codex/skills/. È inclusa in dockup-cli, quindi un normale aggiornamento modifica insieme l'eseguibile e le relative istruzioni:

dockup update

Questo accoppiamento delle versioni è importante quando la superficie dei comandi è ampia. Un agent non dovrebbe mai eseguire un flag ricordato solo perché compariva in un vecchio prompt. Codex dovrebbe usare la skill inclusa nel pacchetto e l'attuale documentazione di riferimento della Dockup CLI come autorità per i comandi.

Per conoscere le motivazioni progettuali alla base delle skill, consulta skill degli agent vs MCP.

Come si autentica Codex senza un terminale interattivo?

Un sandbox o un job CI potrebbe non riuscire a completare un login tramite browser. Imposta un token nell'ambiente del processo:

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

DOCKUP_TOKEN ha la precedenza sul file di configurazione locale. La risposta di whoami indica se la credenziale attiva proviene dall'ambiente o dalla configurazione, aiutando Codex a diagnosticare il caso comune in cui coesistono un token locale obsoleto e un token CI.

Tratta il token come un secret di infrastruttura. Non inserirlo in AGENTS.md, SKILL.md, nel controllo versione, negli esempi di comandi sottoposti a commit nel repository o nel transcript finale dell'agent. In CI, usa l'encrypted secret store della piattaforma ed esponi il valore solo allo step di deployment. Il pattern completo per l'esecuzione non interattiva è descritto in CI/CD con DOCKUP_TOKEN.

Prima di concedere a Codex l'accesso in scrittura, definisci il perimetro delle autorizzazioni. Un ambito iniziale ragionevole include la ricerca dei servizi, il deployment, la lettura dei log e i controlli di stato. L'eliminazione dei database, la distruzione dei servizi, le modifiche ai team e la rimozione della configurazione dovrebbero restare soggette ad approvazione.

Come trova o crea Codex il servizio corretto?

Fai della ricerca il primo comando da eseguire. Non chiedere a Codex di trasformare “Payments API” in uno slug inventato:

dockup services --json

Ogni risultato include un target esatto nel formato project/service. Codex dovrebbe copiare quel valore nei comandi successivi e restituirlo nel riepilogo.

Quando non esiste alcun servizio, creane uno da Git:

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

Il comando crea il servizio, esegue il deployment, attende il completamento dell'operazione e scrive un link .dockup nella directory di lavoro. Se presente, viene utilizzato un Dockerfile; in caso contrario, Nixpacks rileva automaticamente la configurazione di build.

Quando Codex perde lo stato della sessione o un workflow viene rieseguito dopo un'interruzione di rete, dovrebbe individuare nuovamente i servizi e verificare il target esatto prima di modificare qualsiasi cosa. Se il target esiste già, riprendi dal suo stato e dalla cronologia dei deployment invece di inviare un'altra richiesta di creazione.

La sequenza completa, a partire dal repository, è disponibile in Dal repository Git alla produzione.

Come dovrebbe preparare Codex la configurazione prima del deployment?

Chiedi a Codex di esaminare i metadati correnti del servizio prima di modificarli:

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

La risposta dell'ambiente include le chiavi e gli indicatori isSecret, mentre i valori dei secret restano mascherati. Codex può aggiungere separatamente variabili ordinarie e secret:

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

Non inserire mai un secret di produzione in dockup.yaml: il manifest è adatto a una configurazione in chiaro e sottoposta a review, non alle credenziali. Le variabili secret esistenti non vengono sovrascritte né rimosse dal workflow config-as-code.

Configura la porta di ascolto del servizio e il readiness check quando questi valori sono noti:

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

Un readiness gate rende significativa la verifica in produzione. La piattaforma esegue un deployment blue-green e instrada il traffico solo dopo che la nuova versione ha superato il gate.

In che modo la verifica in produzione conferma lo stato terminale?

Per un servizio esistente, usa un unico comando:

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

Il timeout esplicito corrisponde al valore predefinito di 900 secondi e rende visibile l'intento del workflow. L'exit 0 indica che il deployment è riuscito. Un risultato diverso da zero con deploy_failed indica che la build o il deployment hanno raggiunto uno stato di errore. deploy_timeout indica che l'operazione non era ancora in uno stato terminale al termine del periodo di attesa.

La logica corretta di branching di Codex si basa sullo stato del processo:

Risultato	Azione di Codex
Exit 0, status:"success"	Procedi con le verifiche di health, uptime e security
deploy_failed	Leggi i build log e individua il primo errore risolvibile
deploy_timeout	Segnala l'incertezza; controlla lo stato o riprova con un timeout motivato
not_logged_in	Fermati e richiedi un token valido
needs_confirm	Fermati e chiedi l'approvazione di una persona

Dopo un deployment di Codex riuscito, raccogli dati osservabili:

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

I controlli di uptime vengono eseguiti ogni minuto e includono statistiche sui tempi di risposta, come il p95. I risultati di security includono le CVE delle immagini e i controlli di configurazione. Questi segnali non dimostrano che l'applicazione funzioni correttamente dal punto di vista del business, quindi Codex dovrebbe eseguire anche gli smoke test del repository, quando disponibili.

Come dovrebbe diagnosticare e recuperare Codex dopo un release fallito?

Gli errori di build e quelli di runtime richiedono log diversi. Usa l'output dell'ultima build quando il deployment non ha mai raggiunto un container eseguibile:

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

Usa i log di runtime quando l'immagine è stata creata ma l'applicazione va in crash, si associa alla porta sbagliata o si arresta dopo l'avvio:

dockup logs production/payments-api --json

La modalità follow è utile durante una build lunga:

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

In modalità JSON, l'output di follow è NDJSON, consentendo a Codex di elaborare ogni batch non appena arriva. Lo stream termina quando il deployment raggiunge uno stato terminale e conserva l'exit code reale dell'errore.

Il recupero inizia dalla cronologia, non da un target di rollback ipotizzato:

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

Codex dovrebbe individuare un deployment sicuramente riuscito, indicare l'ID selezionato e conservare le prove dell'errore prima di rieseguirlo. Non dovrebbe mai scegliere “il secondo elemento” senza verificare stato e timestamp.

Un report finale utile contiene sette campi: target, branch o commit, ID del deployment, exit code, stato terminale, URL di produzione e azioni successive. Questo formato rende ogni deployment di Codex verificabile da una persona o da uno step di automazione successivo.

Uno script compatto per la verifica

Questo pattern shell mantiene deployment e diagnosi all'interno di un unico flusso di controllo trasparente:

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

Lo script non cerca con grep una frase di successo. Si affida all'exit code della CLI, conserva il JSON del deployment e fa fallire il job chiamante quando la produzione non ha raggiunto lo stato di successo.

Rendi osservabili i retry invece di nasconderli

Le sessioni degli agent possono interrompersi dopo l'avvio di un'operazione ma prima che il risultato raggiunga il transcript. L'esecuzione successiva di Codex non dovrebbe ripetere alla cieca ogni modifica. Dovrebbe individuare nuovamente il servizio, esaminare l'ultimo deployment e stabilire se l'operazione precedente ha raggiunto uno stato terminale.

Un runbook di deployment di Codex dovrebbe classificare i comandi come ripetibili in sicurezza, ripetibili solo dopo un'ispezione o soggetti ad approvazione. Le operazioni di lettura possono essere ripetute senza rischi. La creazione di un servizio richiede prima una fase di discovery. Un nuovo deployment è un nuovo evento di produzione e dovrebbe essere registrato come tale. Le operazioni di pruning e le altre attività distruttive restano decisioni umane.

Separa la verifica della piattaforma da quella dell'applicazione

Dockup può dimostrare che una build è stata completata, che il container è diventato pronto e che probe eseguite al minuto rilevano il servizio pubblico. Codex dovrebbe comunque eseguire controlli specifici dell'applicazione: un endpoint di health pubblico, una richiesta di test autenticata o uno smoke test fornito dal repository che non modifichi i dati dei clienti.

Il risultato finale dovrebbe indicare entrambi i livelli. “Il deployment della piattaforma è riuscito” e “lo smoke test dell'applicazione è riuscito” sono affermazioni diverse. Quando è disponibile solo la prima, Codex dovrebbe dichiararlo invece di comprimere l'incertezza in un segno di spunta verde.

Conferma la superficie dei comandi installata prima dell'automazione

Un task Codex riutilizzabile dovrebbe iniziare controllando dockup skill status --json e aprendo la documentazione di riferimento della CLI corrente quando dipende da un'opzione meno familiare. In questo modo si evita che una sessione segua un esempio scritto per un'altra release.

Il controllo è particolarmente utile nei runner effimeri, dove una nuova installazione globale tramite npm può differire da quella presente sul laptop di uno sviluppatore. Codex può riportare lo stato della skill prima di eseguire la prima modifica in produzione, rendendo il record del deployment riproducibile.

Handoff finale

Conserva le prove.

Mantieni visibile il target

Restituisci il target esatto del servizio nel report finale.

Conserva la decisione sulla sorgente

Registra se Dockup ha utilizzato il Dockerfile del repository o Nixpacks. Questo dato aiuta la sessione Codex successiva a scegliere il build log corretto e impedisce che una modifica nella struttura del sorgente venga scambiata per un incidente della piattaforma.

Registra anche se il deployment automatico al push è abilitato. In caso contrario, un release manuale dell'agent e un release attivato da un push potrebbero sovrapporsi e creare due eventi di produzione a partire dalla stessa analisi.

Porta il workflow in produzione

Esegui il primo deployment di Codex su un servizio usa e getta o a basso rischio, quindi promuovi in produzione lo stesso contratto di comandi già verificato.

npm install -g dockup-cli
dockup skill install

Il primo comando installa la CLI. Il secondo installa la skill Dockup corrispondente per Claude Code e Codex. Inizia gratuitamente su app.dockup.ai.

FAQ

Codex può eseguire il deployment di un nuovo repository Git con un solo comando?

Sì. dockup create può creare il servizio, eseguire il deployment, attendere il risultato terminale e collegare la directory corrente quando viene utilizzato con --deploy, --wait e --link.

Come dovrebbe autenticarsi Codex a Dockup?

Usa DOCKUP_TOKEN nell'ambiente del processo e verificalo con dockup whoami --json. In questo modo si evita il login interattivo tramite browser nei sandbox e in CI.

Cosa dimostra che un deployment di Codex è riuscito?

Il comando di deploy deve terminare con exit 0 dopo essere stato eseguito con --wait, e il relativo JSON deve riportare uno stato terminale riuscito. Prosegui con i controlli di status, uptime e smoke test dell'applicazione.

Codex può leggere i secret di produzione da Dockup?

No. I valori dei secret sono mascherati nell'output. Codex può impostare o sostituire un secret, ma non riceve il valore memorizzato quando elenca la configurazione.

Cosa dovrebbe fare Codex con needs_confirm?

Dovrebbe fermarsi e richiedere un'approvazione umana esplicita. L'errore indica che è stato tentato un comando distruttivo senza la conferma --yes richiesta.