CI/CD pentru agenți AI cu DOCKUP_TOKEN

CI/CD pentru agenți AI funcționează corect doar atunci când autentificarea și deployment-ul se desfășoară fără intervenția unei persoane la terminal. Autentificarea în browser, codurile one-time copiate manual și mesajele de status exprimate doar în text nu sunt compatibile cu un runner nesupravegheat. Dockup oferă un flux non-interactive prin DOCKUP_TOKEN, JSON structurat și comenzi de deployment care returnează un cod real de eroare.

Acest ghid definește un contract de pipeline pe care îl pot utiliza Claude Code, Codex, un shell script sau un job CI convențional. Se aplică aceleași reguli: injectează tokenul la runtime, verifică identitatea, identifică sau specifică targetul exact, așteaptă un rezultat final și păstrează informațiile de diagnostic în caz de eroare.

De ce are nevoie CI/CD-ul pentru agenți AI de autentificare non-interactive?

dockup login interactiv deschide o pagină de autentificare și așteaptă un token. Acest comportament este potrivit pe stația de lucru a unui dezvoltator, însă un runner containerizat poate să nu aibă browser, un director home persistent sau o persoană disponibilă să introducă manual datele.

DOCKUP_TOKEN rezolvă această limitare:

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

Variabila de mediu are prioritate față de ~/.dockup/config.json. whoami raportează tokenSource, astfel încât pipeline-ul poate demonstra că utilizează credentialul injectat intenționat, nu un fișier de configurare vechi rămas pe un runner self-hosted.

Nu rula dockup login -t "$DOCKUP_TOKEN" în CI decât dacă există un motiv specific pentru a persista un fișier de configurare. Furnizarea directă a variabilei de mediu limitează credentialul la procesul respectiv și evită scrierea lui în directorul home al runnerului.

Pipeline-ul nu trebuie să afișeze niciodată tokenul. Dezactivează shell tracing în jurul comenzilor care conțin secrete, evită afișarea întregului environment și folosește funcția platformei CI pentru mascarea secretelor.

Cum trebuie stocat și limitat DOCKUP_TOKEN?

Stochează tokenul ca secret criptat la nivel de repository, environment sau organizație. Pentru producție, este recomandat un secret la nivel de environment, deoarece poate fi combinat cu restricții pentru branch-uri și aprobări manuale oferite de platforma CI.

O politică sigură pentru token trebuie să răspundă la cinci întrebări:

Întrebare	Răspuns recomandat
Unde este stocat tokenul?	În sistemul de secrete criptate al CI
Când este expus?	Doar în jobul de deployment
Ce branch-uri îl pot utiliza?	Branch-uri de producție protejate
Cine poate modifica workflow-ul?	Maintaineri care au trecut prin code review
Cum este verificată utilizarea?	Jurnalul de audit Dockup și istoricul joburilor CI

Dockup acceptă și API keys cu permisiuni. Listează numele permisiunilor disponibile înainte de a crea o cheie cu scope restrâns:

dockup keys permissions --json

Alege doar numele exacte ale permisiunilor returnate de platformă, apoi creează cheia prin workflow-ul pentru API keys cu permisiuni. Preia cheia generată în condiții de siguranță în timpul creării și stocheaz-o imediat; nu o include într-un issue, pull request sau transcript al agentului. Un job de deployment nu ar trebui să moștenească acces extins la administrarea contului doar pentru că un token de dezvoltator are deja aceste permisiuni.

Articolul Măsuri de protecție pentru agenții AI în producție prezintă un model mai amplu de acordare a permisiunilor.

Cum construiești un pipeline de deployment care așteaptă rezultatul real?

Instalează CLI-ul în job, verifică identitatea, apoi fă deployment cu --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

Important nu este furnizorul CI, ci contractul comenzii. dockup deploy ... --wait --json se încheie cu 0 doar atunci când deployment-ul ajunge la succes. Timeout-ul implicit este de 900 de secunde. Un build eșuat returnează un exit code diferit de zero împreună cu deploy_failed; o operațiune care nu ajunge într-o stare finală până la expirarea timeout-ului returnează deploy_timeout.

Deoarece procesul se încheie cu un exit code diferit de zero, runnerul marchează pasul și jobul ca eșuate. Nu este necesară analiza logurilor.

Pentru un repository conectat care trebuie să trimită branch-ul curent și să facă deployment, dockup push --json așteaptă implicit. Într-un job CI care a primit deja un eveniment Git push, dockup deploy <target> este adesea mai clar, deoarece evită efectuarea unui push din runner.

Cum trebuie să captureze un pipeline logurile și codurile de eroare?

Păstrează rezultatul JSON al deployment-ului ca artifact sau output al jobului, dar evită ca o redirecționare să ascundă exit status-ul. Un pattern de shell le poate captura pe ambele:

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

Pipeline-ul se încheie cu statusul original al deployment-ului. Logurile de build sunt colectate doar după o eroare. Logurile de runtime trebuie colectate atunci când imaginea a fost construită, dar aplicația se oprește ulterior:

dockup logs production/api --json

Pentru vizibilitate live asupra build-ului, modul follow emite NDJSON:

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

Fluxul se încheie atunci când se încheie deployment-ul, iar rezultatul eșuat rămâne un rezultat de proces diferit de zero. Secvența detaliată pentru diagnostic este prezentată în depanarea logurilor de build și runtime.

Un pipeline trebuie să se bazeze pe coduri, nu pe fragmente din mesaje:

Cod	Răspunsul pipeline-ului
not_logged_in	Eșuează imediat; injectarea secretului este defectuoasă
no_target	Eșuează; configurația targetului este invalidă
deploy_trigger_failed	Eșuează înainte de așteptare; verifică eroarea returnată
deploy_failed	Încarcă logurile build-ului și marchează execuția ca eșuată
deploy_timeout	Marchează rezultatul ca incert; verifică statusul înainte de retry
needs_confirm	Oprește execuția; un pas distructiv nu are aprobare

Cum poate participa un agent fără a reduce securitatea CI?

Un agent poate pregăti codul, actualiza un workflow verificat, interpreta JSON și rezuma un build eșuat. Nu are nevoie de acces nerestricționat la tokenul de producție în fiecare sesiune de coding.

Separă rolurile:

1. Agentul de dezvoltare: modifică codul și rulează testele local.
2. Procesul de review: validează modificările configurației de deployment.
3. Runnerul CI: primește DOCKUP_TOKEN doar după trigger-ul aprobat.
4. Dockup: execută deployment-ul și înregistrează evenimentele de audit.
5. Agentul sau operatorul: interpretează rezultatul și propune recuperarea.

Această organizare împiedică un prompt injection dintr-o sarcină fără legătură să obțină credentiale de producție. Agentul poate în continuare să înțeleagă pipeline-ul, deoarece comenzile și JSON-ul așteptat sunt versionate în repository, în timp ce valoarea secretului rămâne în afara acestuia.

Pentru deployment-uri rulate direct de agent, injectează tokenul în procesul specific Claude Code sau Codex și instalează skill-ul inclus:

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

Skill-ul le instruiește pe ambele să utilizeze autentificare non-interactive, JSON, identificarea targetului exact, așteptarea unei stări finale și porți de confirmare.

Ce face CI/CD-ul pentru agenți AI repetabil și auditabil?

Repetabilitatea începe cu un target explicit. Stochează production/api ca variabilă de pipeline protejată sau ca valoare literală verificată, nu ca un nume pe care agentul îl derivă la runtime. Validează contul înainte de prima operațiune de scriere.

Idempotența necesită tratamente diferite în funcție de operațiune:

• Citirea identității, statusului, logurilor și istoricului poate fi repetată în siguranță.
• Crearea unui serviciu trebuie să înceapă cu identificarea targetului, astfel încât retry-urile să nu creeze duplicate.
• Un nou deployment creează un alt eveniment de producție și trebuie înregistrat.
• Modificările de environment sunt mutații și necesită un redeploy.
• Distrugerea și pruning-ul nu trebuie să fie ținte automate pentru retry.

După deployment, colectează dovezi din platformă:

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

Uptime-ul este măsurat în fiecare minut și include timpul mediu de răspuns și p95. Datele de audit conectează mutația CI cu verificarea ulterioară. Consumul de CPU, RAM și disk este, de asemenea, măsurat minut de minut în raport cu balanța contului; planul Pro recomandat costă 20 USD pe lună și include un credit de utilizare de 20 USD.

O evidență completă a pipeline-ului include commit-ul Git, targetul Dockup, ID-ul deployment-ului, timestamp-urile de început și finalizare, exit code-ul, statusul final și linkurile către artifactele de build. Astfel, un release de CI/CD pentru agenți AI rămâne reproductibil chiar și atunci când sesiunea inițială a agentului nu mai există.

Referința Dockup CLI trebuie tratată ca autoritatea pentru comenzi. Pentru crearea repository-ului înainte de activarea CI, urmează ghidul De la repository Git la producție.

Controlează concurența și promovarea între environment-uri

Două pipeline-uri reușite pot crea totuși un release nesigur dacă rulează simultan pe același target. Folosește mecanismele de concurrency ale platformei CI, astfel încât un job nou de producție fie să aștepte jobul vechi, fie să îl înlocuiască în mod deliberat. Dockup va raporta corect fiecare deployment, însă workflow-ul repository-ului trebuie să decidă ordinea commit-urilor care se suprapun.

Promovează același commit verificat între environment-uri, în loc să reconstruiești o stare locală care nu este urmărită. Un job de staging poate face deployment pentru staging/api, poate rula verificări ale aplicației, apoi poate permite unui job de producție protejat să facă deployment pentru production/api. Păstrează tokenurile și targeturile distincte, astfel încât un agent de staging să nu poată trece accidental de această graniță.

Definește o politică de retry pentru timeout-uri

deploy_timeout nu înseamnă nici eșec, nici succes. Înseamnă că operațiunea era încă în desfășurare atunci când s-a încheiat așteptarea de 900 de secunde. Înainte de retry, verifică:

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

Dacă deployment-ul inițial a ajuns ulterior la succes, un retry făcut fără verificare ar crea un alt release. Dacă a eșuat, colectează logul de build. Dacă încă nu a ajuns într-o stare finală, iar build-ul este legitim de lung, reia observarea cu un timeout mai mare, documentat, în loc să creezi un al doilea deployment.

Această distincție împiedică CI/CD-ul pentru agenți AI să transforme incertitudinea de rețea sau de sincronizare în modificări duplicate în producție.

Înregistrează identitatea deployment-ului

Include în sumarul CI identitatea contului Dockup, targetul, SHA-ul commit-ului, ID-ul deployment-ului și statusul final. Această evidență simplă îi permite unui operator ulterior să asocieze execuția pipeline-ului cu evenimentele de audit Dockup fără a expune tokenul.

Pune workflow-ul în producție

Instalează CLI-ul în runner, verifică identitatea injectată și folosește statusul final al procesului — nu o linie de log care pare să indice succesul — ca gate pentru pipeline.

npm install -g dockup-cli
dockup skill install

Prima comandă instalează CLI-ul. A doua instalează skill-ul Dockup compatibil cu Claude Code și Codex. Începe gratuit la app.dockup.ai.

Întrebări frecvente

Ce este DOCKUP_TOKEN?

DOCKUP_TOKEN este metoda de autentificare bazată pe environment pentru sesiunile Dockup CLI care nu pot finaliza autentificarea interactivă în browser, inclusiv runneri CI, containere și agenți AI.

Înlocuiește DOCKUP_TOKEN un fișier local de configurare Dockup?

Da. Tokenul din environment are prioritate, iar dockup whoami --json raportează sursa activă a tokenului.

Cum știe un job CI că un deployment Dockup a eșuat?

Rulează dockup deploy cu --wait și --json. Comanda se încheie cu un exit code diferit de zero și un cod de eroare structurat atunci când deployment-ul eșuează sau expiră.

Ar trebui un workflow CI să afișeze tokenul de deployment pentru debugging?

Nu. Păstrează-l în sistemul de secrete CI, evită shell tracing și dump-urile de environment și expune-l doar pasului de deployment.

Pot folosi Claude Code sau Codex aceeași metodă de autentificare CI?

Da. Ambele pot utiliza DOCKUP_TOKEN și skill-ul Dockup inclus, care le învață aceleași reguli pentru JSON, identificarea targetului, așteptare și confirmare.