AI-ügynökös CI/CD DOCKUP_TOKEN használatával

Az AI-ügynökös CI/CD csak akkor működik megbízhatóan, ha a hitelesítés és a telepítés terminálnál ülő felhasználó nélkül is megfelelően működik. A böngészős bejelentkezés, az egyszer használatos kódok bemásolása és a kizárólag szöveges állapotüzenetek nem kompatibilisek a felügyelet nélküli runnerrel. A Dockup a nem interaktív folyamatot a DOCKUP_TOKEN, a strukturált JSON és a valódi hibás kilépési kódot visszaadó deploy parancsok használatával támogatja.

Ez az útmutató olyan pipeline-szerződést mutat be, amelyet a Claude Code, a Codex, egy shell script vagy egy hagyományos CI-feladat egyaránt használhat. A szabályok ugyanazok: a tokent futásidőben injektáld, ellenőrizd az identitást, derítsd fel vagy add meg a pontos célt, várd meg a terminálállapotot, és hiba esetén őrizd meg a diagnosztikai adatokat.

Miért van szüksége az AI-ügynökös CI/CD-nek nem interaktív hitelesítésre?

Az interaktív dockup login megnyit egy hitelesítési oldalt, majd tokenre vár. Ez megfelelő egy fejlesztői munkaállomáson, egy konténerizált runner azonban böngésző, tartós home könyvtár vagy a beillesztésre kész felhasználó nélkül is működhet.

A DOCKUP_TOKEN ezt a határvonalat oldja meg:

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

A környezeti változó elsőbbséget élvez a ~/.dockup/config.json fájllal szemben. A whoami jelenti a tokenSource értékét is, így a pipeline bizonyítani tudja, hogy a beillesztett hitelesítő adatot használja, nem pedig egy önállóan üzemeltetett runneren ott maradt régi konfigurációs fájlt.

CI-környezetben ne futtasd a dockup login -t "$DOCKUP_TOKEN" parancsot, hacsak nincs konkrét okod konfigurációs fájl mentésére. A környezeti változó közvetlen megadása a folyamatra korlátozza a hitelesítő adat érvényességét, és elkerüli annak kiírását a runner home könyvtárába.

A pipeline soha nem írhatja ki a tokent. Kapcsold ki a shell tracinget titkokat tartalmazó parancsok körül, ne írasd ki a teljes környezetet, és használd a CI-platform maszkolt titkokhoz biztosított funkcióját.

Hogyan kell tárolni és korlátozni a DOCKUP_TOKEN hatókörét?

A tokent titkosított repository-, környezeti vagy szervezeti titokként tárold. Éles környezetben előnyösebb a környezeti szintű titok használata, mert ez kombinálható a CI-platform által biztosított branch-korlátozásokkal és manuális jóváhagyásokkal.

A biztonságos tokenházirend öt kérdésre ad választ:

Kérdés	Javasolt válasz
Hol tároljuk a tokent?	A CI titkosított titoktárolójában
Mikor válik elérhetővé?	Csak a telepítési jobban
Mely branchek használhatják?	A védett production branchek
Ki módosíthatja a workflow-t?	Ellenőrzött módosításokat végző maintainerök
Hogyan ellenőrizzük a használatát?	A Dockup auditnaplójával és a CI-job előzményeivel

A Dockup jogosultságokkal korlátozott API-kulcsokat is támogat. A szűk hatókörű kulcs létrehozása előtt listázd az elérhető jogosultságneveket:

dockup keys permissions --json

Csak a platform által visszaadott pontos jogosultságneveket válaszd, majd a kulcsot a jogosultságokkal korlátozott API-kulcsok létrehozási folyamatán keresztül hozd létre. A generált kulcsot a létrehozás során biztonságosan rögzítsd, majd azonnal tárold el; ne szerepeljen issue-ban, pull requestben vagy agent transcriptben. Egy deployment jobnak nem kell széles körű fiókadminisztrációs hozzáférést örökölnie csak azért, mert egy fejlesztői token már rendelkezik vele.

Az AI-ügynökök production környezetre vonatkozó védőkorlátai című cikk részletesebb jogosultsági létrát mutat be.

Hogyan építsünk a tényleges állapotot megváró telepítési pipeline-t?

Telepítsd a CLI-t a jobban, ellenőrizd az identitást, majd indítsd a deployt --wait kapcsolóval:

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

Nem a CI-szolgáltató a lényeg, hanem a parancs szerződése. A dockup deploy ... --wait --json csak akkor lép ki 0 kóddal, ha a telepítés sikeresen befejeződik. Az alapértelmezett timeout 900 másodperc. A sikertelen build nem nulla kilépési kóddal és deploy_failed értékkel tér vissza; ha a művelet a timeout lejártakor még nem terminális állapotú, a visszatérési érték deploy_timeout.

Mivel a folyamat nem nulla kóddal lép ki, a runner sikertelenként jelöli a lépést és a jobot. Nincs szükség a naplók elemzésére.

Ha egy kapcsolt repository-nak az aktuális branchet is pusholnia, majd deployolnia kell, a dockup push --json alapértelmezés szerint megvárja a művelet végét. Egy olyan CI-jobban azonban, amely már Git push eseményt kapott, gyakran egyértelműbb az explicit dockup deploy <target>, mert így elkerülhető a runnerből indított push.

Hogyan rögzítse a pipeline a naplókat és a hibakódokat?

A JSON-formátumú deploymenteredményt őrizd meg artifactként vagy jobkimenetként, de ügyelj arra, hogy egy átirányítás ne rejtse el a kilépési állapotot. Egy shell-minta mindkettőt rögzíteni tudja:

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

A pipeline az eredeti deploy-állapottal lép ki. A buildnaplókat csak hiba után gyűjti be. A futásidejű naplókat akkor kell begyűjteni, ha az image felépült, de az alkalmazás később összeomlik:

dockup logs production/api --json

Az élő buildállapot követéséhez a follow mód NDJSON-t bocsát ki:

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

A stream a deployment befejezésekor lezárul, hiba esetén pedig továbbra is nem nulla folyamat-eredmény keletkezik. A részletes diagnosztikai folyamatot a build- és runtime-naplók hibakereséséről szóló útmutató ismerteti.

A pipeline-oknak kódok, nem pedig üzenetrészletek alapján kell elágazniuk:

Kód	Pipeline-válasz
not_logged_in	Azonnali hibajelzés; a titok injektálása hibás
no_target	Hibajelzés; a célkonfiguráció érvénytelen
deploy_trigger_failed	Hibajelzés a várakozás megkezdése előtt; vizsgáld meg a visszaadott hibát
deploy_failed	Töltsd fel a buildnaplókat, majd jelezz hibát
deploy_timeout	Jelöld bizonytalanként; újrapróbálás előtt ellenőrizd az állapotot
needs_confirm	Állj le; egy destruktív lépéshez hiányzik a jóváhagyás

Hogyan vehet részt egy agent a CI biztonságának gyengítése nélkül?

Egy agent előkészítheti a kódot, frissíthet egy ellenőrzött workflow-t, értelmezheti a JSON-t, és összefoglalhatja egy sikertelen build eredményét. Nem szükséges, hogy minden kódolási munkamenetben korlátlan hozzáférése legyen a production tokenhez.

Válaszd külön a szerepköröket:

1. Fejlesztési agent: helyben módosítja a kódot és futtatja a teszteket.
2. Review-folyamat: ellenőrzi a telepítési konfiguráció módosításait.
3. CI-runner: csak a jóváhagyott trigger után kapja meg a DOCKUP_TOKEN értékét.
4. Dockup: végrehajtja a telepítést, és rögzíti az audit eseményeit.
5. Agent vagy operátor: értelmezi az eredményt, és helyreállítási javaslatot tesz.

Ez a felépítés megakadályozza, hogy egy nem kapcsolódó feladatban elhelyezett prompt injection production hitelesítő adatokhoz jusson. Az agent ettől még megértheti a pipeline működését, mert a parancsok és a várt JSON a repository-ban szerepelnek, a titok értéke viszont azon kívül marad.

Közvetlenül agent által indított telepítéshez injektáld a tokent az adott Claude Code- vagy Codex-folyamatba, majd telepítsd a mellékelt skillt:

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

A skill mindkét agentet nem interaktív hitelesítés, JSON, pontos célfelderítés, terminálállapot megvárása és jóváhagyási kapuk használatára utasítja.

Mitől lesz az AI-ügynökös CI/CD megismételhető és auditálható?

A megismételhetőség explicit céllal kezdődik. A production/api értékét védett pipeline-változóként vagy ellenőrzött literálként tárold, ne olyan névként, amelyet az agent futásidőben vezet le. Az első írási művelet előtt ellenőrizd a fiókot.

Az idempotencia műveletenként eltérő kezelést igényel:

• Az identitás, az állapot, a naplók és az előzmények lekérdezése biztonságosan megismételhető.
• A szolgáltatás létrehozását célfelderítéssel kell kezdeni, hogy az újrapróbálkozások ne hozzanak létre duplikátumot.
• Az újbóli deploy újabb production eseményt hoz létre, ezért rögzíteni kell.
• A környezeti módosítások mutációk, amelyek újabb redeployt igényelnek.
• A törlés és a pruning nem lehet automatikusan újrapróbálható művelet.

A telepítés után gyűjts bizonyítékokat a platformról:

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

Az uptime mérése percenként történik, és az átlagos, valamint a p95 válaszidőt is tartalmazza. Az auditkimenet összekapcsolja a CI által végrehajtott mutációt a későbbi ellenőrzéssel. A CPU-, RAM- és lemezhasználatot szintén percenként mérik a fiókegyenleghez viszonyítva; az ajánlott Pro csomag havi 20 dollár, 20 dollár értékű használati kredittel.

Egy teljes pipeline-rekord tartalmazza a Git commitot, a Dockup célt, a deployment ID-ját, a kezdési és befejezési időpontot, a kilépési kódot, a terminálállapotot és a build artifactokra mutató hivatkozásokat. Így egy AI-ügynökös CI/CD kiadás akkor is reprodukálható marad, ha az eredeti agent-munkamenet már nem érhető el.

A Dockup CLI-referenciát kell tekinteni a parancsok elsődleges forrásának. A CI engedélyezése előtti repository-létrehozáshoz kövesd a Git repository-tól a productionig című útmutatót.

A konkurencia és a környezetek közötti előléptetés kezelése

Két sikeres pipeline is létrehozhat nem biztonságos kiadást, ha ugyanazon a célon párhuzamosan futnak. Használd a CI-platform konkurenciakezelését, hogy az újabb production job megvárja a régebbit, vagy szándékosan lecserélje azt. A Dockup minden deploymentet pontosan jelent, de az átfedő commitok sorrendjéről a repository workflow-jának kell döntenie.

Ugyanazt az ellenőrzött commitot léptesd elő a környezetek között, ahelyett hogy egy nem követett helyi állapotot építenél újra. Egy staging job telepítheti a staging/api célt, lefuttathatja az alkalmazás ellenőrzéseit, majd engedélyezheti, hogy egy védett production job a production/api célra telepítsen. A tokeneket és a célokat tartsd külön, hogy egy staging agent véletlenül se léphesse át a határt.

Határozz meg újrapróbálási szabályt timeout esetére

A deploy_timeout nem jelent sem hibát, sem sikert. Azt jelenti, hogy a művelet még futott, amikor a 900 másodperces várakozás véget ért. Újrapróbálkozás előtt ellenőrizd:

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

Ha az eredeti deployment később sikeresen befejeződött, a vakon indított újrapróbálás újabb kiadást hozna létre. Ha sikertelen lett, gyűjtsd be a buildnaplót. Ha továbbra sem terminális állapotú, és a build indokoltan hosszú, nagyobb, dokumentált timeout mellett folytasd a megfigyelést ahelyett, hogy második deploymentet hoznál létre.

Ez a megkülönböztetés megakadályozza, hogy az AI-ügynökös CI/CD hálózati vagy időzítési bizonytalanságot duplikált production-módosításokká alakítsa.

Rögzítsd a deployment identitását

A CI-összefoglaló tartalmazza a Dockup-fiók identitását, a célt, a commit SHA-t, a deployment ID-ját és a terminálállapotot. Ez a kis rekord lehetővé teszi, hogy egy későbbi operátor a pipeline-futtatást a Dockup audit eseményeihez kapcsolja anélkül, hogy hozzáférne a tokenhez.

Élesítsd a workflow-t

Telepítsd a CLI-t a runnerre, ellenőrizd az injektált identitást, és ne egy sikeresnek tűnő naplósor, hanem a terminálállapotból származó kilépési kód legyen a pipeline kapuja.

npm install -g dockup-cli
dockup skill install

Az első parancs telepíti a CLI-t. A második a Claude Code és a Codex számára elérhető, megfelelő Dockup skillt telepíti. Kezdd el ingyen az app.dockup.ai oldalon.

GYIK

Mi az a DOCKUP_TOKEN?

A DOCKUP_TOKEN a Dockup CLI-munkamenetek környezeti változón alapuló hitelesítési módja, amely olyan esetekben használható, amikor az interaktív böngészős bejelentkezés nem hajtható végre, például CI-runnerekben, konténerekben és AI-ügynököknél.

Felülírja a DOCKUP_TOKEN a helyi Dockup-konfigurációs fájlt?

Igen. A környezeti token elsőbbséget élvez, és a dockup whoami --json jelenti az aktív tokenforrást.

Honnan tudja egy CI-job, hogy a Dockup deployment sikertelen lett?

Futtasd a dockup deploy parancsot a --wait és a --json kapcsolóval. A parancs strukturált hibakóddal és nem nulla kilépési kóddal tér vissza, ha a deploy sikertelen vagy timeout miatt megszakad.

Kiírhatja egy CI-workflow a deployment tokent hibakeresés céljából?

Nem. Tartsd a CI titoktárolójában, kerüld a shell tracinget és a környezeti változók kiíratását, és csak a telepítési lépés számára tedd elérhetővé.

Használhatja a Claude Code vagy a Codex ugyanazt a CI-hitelesítési folyamatot?

Igen. Mindkettő használhatja a DOCKUP_TOKEN értékét és a mellékelt Dockup skillt, amely ugyanazokat a JSON-, célfelderítési, várakozási és jóváhagyási szabályokat tanítja meg.