CI/CD per agenti AI con DOCKUP_TOKEN

Il CI/CD per agenti AI funziona correttamente solo quando autenticazione e deployment operano senza una persona davanti al terminale. Il login tramite browser, i codici monouso copiati manualmente e i messaggi di stato espressi solo in linguaggio naturale sono incompatibili con un runner non presidiato. Dockup supporta il flusso non interattivo tramite DOCKUP_TOKEN, JSON strutturato e comandi di deployment che restituiscono un vero exit code di errore.

Questa guida definisce un contratto di pipeline utilizzabile da Claude Code, Codex, uno shell script o un normale job CI. Le regole sono sempre le stesse: iniettare il token a runtime, verificare l’identità, individuare o specificare il target esatto, attendere un risultato finale e preservare i dati diagnostici in caso di errore.

Perché il CI/CD per agenti AI richiede un’autenticazione non interattiva?

Il comando interattivo dockup login apre una pagina di autenticazione e attende un token. È adatto a una workstation di sviluppo, ma un runner containerizzato potrebbe non avere un browser, una home directory persistente o una persona disponibile per incollare il codice.

DOCKUP_TOKEN risolve questo limite:

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

La variabile d’ambiente ha la precedenza su ~/.dockup/config.json. whoami restituisce tokenSource, così la pipeline può dimostrare di utilizzare la credenziale iniettata prevista invece di un vecchio file di configurazione rimasto su un runner self-hosted.

In CI, non eseguire dockup login -t "$DOCKUP_TOKEN" a meno che non ci sia un motivo specifico per salvare un file di configurazione. Fornire direttamente la variabile d’ambiente mantiene la credenziale limitata al processo ed evita di scriverla nella home directory del runner.

La pipeline non deve mai stampare il token. Disabilita il tracing della shell intorno ai comandi che contengono secret, evita di stampare l’intero ambiente e utilizza la funzione della piattaforma CI per mascherare i secret.

Come devono essere archiviati e limitati i permessi di DOCKUP_TOKEN?

Archivia il token come secret crittografato a livello di repository, ambiente od organizzazione. Per la produzione, preferisci un secret a livello di ambiente, perché può essere associato a restrizioni sui branch e ad approvazioni manuali offerte dalla piattaforma CI.

Una policy sicura per i token deve rispondere a cinque domande:

Domanda	Risposta consigliata
Dove viene archiviato il token?	Secret store crittografato della CI
Quando viene esposto?	Solo nel job di deployment
Quali branch possono usarlo?	Branch di produzione protetti
Chi può modificare il workflow?	Maintainer che hanno superato una review
Come viene verificato l’utilizzo?	Audit log di Dockup e cronologia dei job CI

Dockup supporta anche API key con permessi specifici. Elenca i nomi dei permessi disponibili prima di creare una chiave con scope ridotto:

dockup keys permissions --json

Scegli esclusivamente i nomi esatti dei permessi restituiti dalla piattaforma, quindi crea la chiave tramite il flusso per le API key con permessi. Acquisisci la chiave generata in modo sicuro durante la creazione e archiviala immediatamente; non inserirla in un’issue, in una pull request o nel transcript di un agente. Un job di deployment non dovrebbe ereditare ampi privilegi di amministrazione dell’account solo perché un token dello sviluppatore li possiede già.

L’articolo protezioni per gli agenti AI in produzione illustra una gerarchia di permessi più ampia.

Come si costruisce una pipeline di deployment che attende il risultato effettivo?

Installa la CLI nel job, verifica l’identità ed esegui il deployment con --wait:

name: production-deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DOCKUP_TOKEN: ${{ secrets.DOCKUP_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Dockup CLI
        run: npm install -g dockup-cli

      - name: Verify Dockup identity
        run: dockup whoami --json

      - name: Deploy and wait
        run: dockup deploy production/api --wait --json

La parte importante non è il provider CI, ma il contratto del comando. dockup deploy ... --wait --json restituisce 0 solo quando il deployment raggiunge lo stato di successo. Il timeout predefinito è di 900 secondi. Una build non riuscita restituisce un exit code diverso da zero con deploy_failed; un’operazione non arrivata a uno stato finale allo scadere del timeout restituisce deploy_timeout.

Poiché il processo termina con un exit code diverso da zero, il runner contrassegna lo step e il job come non riusciti. Non è necessario analizzare i log.

Per un repository collegato che deve eseguire il push del branch corrente e il deployment, dockup push --json attende per impostazione predefinita. In un job CI che ha già ricevuto un evento Git push, un comando esplicito dockup deploy <target> è spesso più chiaro, perché evita di eseguire un push dal runner.

Come deve una pipeline acquisire log e codici di errore?

Conserva il risultato JSON del deployment come artifact o output del job, ma evita che una redirezione nasconda l’exit status. Uno schema shell può acquisire entrambi:

set +e
dockup deploy production/api --wait --json > deploy-result.json
status=$?
set -e

if [ "$status" -ne 0 ]; then
  dockup logs production/api --build --json > build-logs.json || true
  cat deploy-result.json
  exit "$status"
fi

dockup status production/api --json

La pipeline termina con lo status originale del deployment. I build log vengono raccolti solo dopo un errore. I runtime log devono essere raccolti quando l’immagine è stata compilata ma l’applicazione va in crash successivamente:

dockup logs production/api --json

Per visualizzare in tempo reale la build, la modalità follow produce NDJSON:

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

Lo stream termina quando termina il deployment e, in caso di errore, il processo continua a restituire un exit code diverso da zero. La sequenza diagnostica dettagliata è descritta nell’articolo debug dei log di build e runtime.

Una pipeline deve diramare in base ai codici, non a frammenti dei messaggi:

Codice	Risposta della pipeline
not_logged_in	Interrompi immediatamente: l’iniezione del secret non funziona
no_target	Interrompi: la configurazione del target non è valida
deploy_trigger_failed	Interrompi prima dell’attesa e analizza l’errore restituito
deploy_failed	Carica i build log e interrompi la pipeline
deploy_timeout	Contrassegna il risultato come incerto e controlla lo stato prima di riprovare
needs_confirm	Interrompi: uno step distruttivo non dispone dell’approvazione

Come può partecipare un agente senza indebolire la sicurezza della CI?

Un agente può preparare il codice, aggiornare un workflow sottoposto a review, interpretare il JSON e riassumere una build non riuscita. Non ha bisogno di un accesso senza restrizioni al token di produzione durante ogni sessione di coding.

Separa i ruoli:

1. Agente di sviluppo: modifica il codice ed esegue i test localmente.
2. Processo di review: convalida le modifiche alla configurazione di deployment.
3. Runner CI: riceve DOCKUP_TOKEN solo dopo il trigger approvato.
4. Dockup: esegue il deployment e registra gli eventi di audit.
5. Agente o operatore: interpreta il risultato e propone il ripristino.

Questa organizzazione impedisce a un prompt injection presente in un’attività non correlata di ottenere credenziali di produzione. L’agente può comunque comprendere la pipeline perché i comandi e il JSON previsto sono salvati nel repository, mentre il valore del secret rimane al di fuori del repository.

Per eseguire deployment direttamente tramite un agente, inietta il token nel processo specifico di Claude Code o Codex e installa la skill inclusa:

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

La skill istruisce entrambi gli agenti a usare autenticazione non interattiva, JSON, individuazione del target esatto, attesa dello stato finale e gate di conferma.

Cosa rende il CI/CD per agenti AI ripetibile e verificabile?

La ripetibilità inizia da un target esplicito. Archivia production/api come variabile di pipeline protetta o come valore letterale sottoposto a review, non come un nome che l’agente ricava a runtime. Convalida l’account prima della prima operazione di scrittura.

L’idempotenza richiede trattamenti diversi a seconda dell’operazione:

• La lettura di identità, stato, log e cronologia può essere ripetuta senza rischi.
• La creazione di un servizio deve iniziare dall’individuazione del target, così i retry non creano duplicati.
• Un nuovo deployment genera un altro evento di produzione e deve essere registrato.
• Le modifiche all’ambiente sono mutazioni e richiedono un nuovo deployment.
• Distruzione e pruning non devono essere target automatici dei retry.

Dopo il deployment, raccogli le evidenze della piattaforma:

dockup status production/api --json
dockup uptime production/api --hours 24 --json
dockup audit --writes --json

L’uptime viene misurato ogni minuto e include il tempo medio di risposta e il p95. L’output dell’audit collega la mutazione eseguita dalla CI alle verifiche successive. Anche il consumo di CPU, RAM e disco viene misurato ogni minuto rispetto al saldo dell’account; il piano Pro consigliato costa 20 $ al mese con 20 $ di credito per l’utilizzo.

Un record completo della pipeline include il commit Git, il target Dockup, l’ID del deployment, i timestamp di inizio e fine, l’exit code, lo stato finale e i link agli artifact di build. In questo modo, una release di CI/CD per agenti AI rimane riproducibile anche quando la sessione originale dell’agente non è più disponibile.

La reference della Dockup CLI deve essere considerata l’autorità per i comandi. Per creare il repository prima di abilitare la CI, segui la guida Dal repository Git alla produzione.

Controlla la concorrenza e la promozione tra ambienti

Due pipeline completate con successo possono comunque creare una release non sicura se vengono eseguite contemporaneamente sullo stesso target. Usa i controlli di concorrenza della piattaforma CI, in modo che un nuovo job di produzione attenda quello precedente oppure lo sostituisca deliberatamente. Dockup riporterà correttamente ogni deployment, ma sarà il workflow del repository a dover decidere l’ordine dei commit sovrapposti.

Promuovi lo stesso commit sottoposto a review tra gli ambienti invece di ricostruire uno stato locale non tracciato. Un job di staging può eseguire il deployment di staging/api, eseguire i controlli dell’applicazione e consentire quindi a un job di produzione protetto di eseguire il deployment di production/api. Mantieni distinti token e target, così un agente di staging non può oltrepassare accidentalmente il confine.

Definisci una policy di retry per i timeout

deploy_timeout non significa né errore né successo. Significa che l’operazione era ancora in corso allo scadere dei 900 secondi di attesa. Prima di riprovare, controlla:

dockup status production/api --json
dockup deployments production/api -n 5 --json

Se il deployment originale raggiunge successivamente lo stato di successo, un retry eseguito alla cieca creerebbe un’altra release. Se è fallito, raccogli il build log. Se è ancora in uno stato non finale e la build è legittimamente lunga, ripeti l’osservazione con un timeout più ampio e documentato invece di creare un secondo deployment.

Questa distinzione impedisce al CI/CD per agenti AI di trasformare l’incertezza dovuta alla rete o ai tempi in modifiche duplicate alla produzione.

Registra l’identità del deployment

Includi nel riepilogo CI l’identità dell’account Dockup, il target, lo SHA del commit, l’ID del deployment e lo stato finale. Questo piccolo record consente a un operatore di collegare in seguito l’esecuzione della pipeline agli eventi di audit di Dockup senza esporre il token.

Porta il workflow in produzione

Installa la CLI nel runner, verifica l’identità iniettata e fai dell’exit status finale, non di una riga di log dall’aspetto positivo, il gate della pipeline.

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.

Domande frequenti

Che cos’è DOCKUP_TOKEN?

DOCKUP_TOKEN è il metodo di autenticazione basato su variabile d’ambiente per le sessioni della Dockup CLI che non possono completare un login interattivo tramite browser, inclusi runner CI, container e agenti AI.

DOCKUP_TOKEN sostituisce un file di configurazione locale di Dockup?

Sì. Il token nell’ambiente ha la precedenza e dockup whoami --json restituisce la sorgente del token attivo.

Come fa un job CI a sapere che un deployment Dockup è fallito?

Esegui dockup deploy con --wait e --json. Il comando termina con un exit code diverso da zero e un codice di errore strutturato quando il deployment fallisce o va in timeout.

Un workflow CI deve stampare il token di deployment per il debug?

No. Conservalo nel secret store della CI, evita il tracing della shell e il dump delle variabili d’ambiente ed esponilo solo allo step di deployment.

Claude Code o Codex possono usare lo stesso metodo di autenticazione CI?

Sì. Entrambi possono usare DOCKUP_TOKEN e la skill Dockup inclusa, che insegna le stesse regole relative a JSON, individuazione del target, attesa e conferma.