AI agent CI/CD s DOCKUP_TOKEN

AI agent CI/CD funguje spolehlivě jen tehdy, když autentizace a deployment proběhnou správně bez člověka u terminálu. Přihlášení v prohlížeči, ruční zadávání jednorázových kódů a stavové zprávy pouze ve formě textu nejsou kompatibilní s unattended runnerem. Dockup podporuje neinteraktivní postup prostřednictvím DOCKUP_TOKEN, strukturovaného JSON a deploy příkazů, které při chybě vracejí skutečný nenulový exit code.

Tato příručka definuje kontrakt pipeline, který může používat Claude Code, Codex, shell script i běžná CI job. Pravidla jsou stejná: token injectujte až za běhu, ověřte identitu, zjistěte nebo přesně určete target, počkejte na finální výsledek a při chybě zachovejte diagnostiku.

Proč AI agent CI/CD potřebuje neinteraktivní autentizaci?

Interaktivní dockup login otevře autentizační stránku a čeká na token. To je vhodné pro vývojářskou pracovní stanici, ale containerizovaný runner nemusí mít prohlížeč, persistentní home directory ani člověka, který by cokoli ručně zadal.

DOCKUP_TOKEN tuto hranici řeší:

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

Environment variable má přednost před ~/.dockup/config.json. whoami vrací tokenSource, takže pipeline může ověřit, že používá zamýšlený injectnutý credential, a ne starý konfigurační soubor ponechaný na self-hosted runneru.

V CI nespouštějte dockup login -t "$DOCKUP_TOKEN", pokud nemáte konkrétní důvod pro persistenci konfiguračního souboru. Přímé předání environment variable udrží credential vázaný na daný proces a zabrání jeho zápisu do home directory runneru.

Pipeline nesmí token nikdy vypsat. U příkazů pracujících se secrets vypněte shell tracing, nevypisujte celé prostředí a používejte mechanismus CI platformy pro maskování secrets.

Jak DOCKUP_TOKEN ukládat a omezit jeho scope?

Token uložte jako šifrovaný secret na úrovni repository, environmentu nebo organizace. Pro produkci preferujte secret na úrovni environmentu, protože jej lze kombinovat s omezením podle branchí a ručním schvalováním, které CI platforma poskytuje.

Bezpečná pravidla pro token musí zodpovědět pět otázek:

Otázka	Doporučená odpověď
Kde je token uložen?	Šifrovaný CI secret store
Kdy je zpřístupněn?	Pouze v deployment jobu
Které branche jej mohou používat?	Chráněné produkční branche
Kdo může workflow měnit?	Maintaineři po code review
Jak se používání kontroluje?	Audit log Dockup a historie CI jobů

Dockup podporuje také API keys s omezenými oprávněními. Před vytvořením úzce scopeovaného klíče si vypište dostupné názvy oprávnění:

dockup keys permissions --json

Vyberte pouze přesné názvy oprávnění vrácené platformou a poté klíč vytvořte prostřednictvím workflow pro API keys s oprávněními. Vygenerovaný klíč při vytváření bezpečně zachyťte a okamžitě uložte. Neuvádějte jej v issue, pull requestu ani transcriptu agenta; deployment job by neměl automaticky získat širokou správu účtu jen proto, že ji má vývojářský token.

Článek Ochranná pravidla pro AI agenty v produkci popisuje širší model oprávnění.

Jak vytvořit deployment pipeline, která čeká na skutečný výsledek?

Nainstalujte CLI v jobu, ověřte identitu a poté spusťte deployment s --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

Podstatný není konkrétní CI vendor, ale kontrakt příkazu. dockup deploy ... --wait --json skončí s 0 pouze tehdy, když deployment dosáhne úspěšného stavu. Výchozí timeout je 900 sekund. Neúspěšný build vrací nenulový exit code s deploy_failed; operace, která při vypršení timeoutu ještě není ve finálním stavu, vrací deploy_timeout.

Protože proces skončí s nenulovým exit code, runner označí step i celý job jako neúspěšný. Není potřeba parsovat logy.

U linked repository, které má odeslat aktuální branch a provést deployment, dockup push --json standardně čeká. V CI jobu, který už obdržel událost Git push, bývá přehlednější explicitní dockup deploy <target>, protože zabrání pushování z runneru.

Jak má pipeline zachytávat logy a error codes?

Výsledek deploymentu v JSON zachovejte jako artifact nebo job output, ale nedovolte, aby redirection skryl exit status. Shell pattern může zachytit obojí:

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 skončí s původním deploy statusem. Build logy se načtou pouze po chybě. Runtime logy je vhodné načíst tehdy, když se image sestaví, ale aplikace později spadne:

dockup logs production/api --json

Pro živý přehled o buildu režim follow vypisuje NDJSON:

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

Stream skončí současně s deploymentem a při chybě zůstává výsledkem procesu nenulový exit code. Podrobnou diagnostickou sekvenci popisuje debugging build a runtime logů.

Pipeline by měla větvit podle kódů, ne podle fragmentů zpráv:

Kód	Reakce pipeline
not_logged_in	Okamžitě selhat; injectování secretu nefunguje
no_target	Selhat; konfigurace targetu je neplatná
deploy_trigger_failed	Selhat ještě před čekáním; zkontrolovat vrácenou chybu
deploy_failed	Nahrát build logy a selhat
deploy_timeout	Označit jako nejisté; před retry zkontrolovat status
needs_confirm	Zastavit; destruktivní krok nemá schválení

Jak může agent fungovat, aniž by oslaboval bezpečnost CI?

Agent může připravovat kód, upravovat workflow po review, interpretovat JSON a shrnout neúspěšný build. Nemusí mít neomezený přístup k produkčnímu tokenu během každé coding session.

Oddělte jednotlivé role:

1. Development agent: lokálně upravuje kód a testy.
2. Review process: ověřuje změny deployment konfigurace.
3. CI runner: obdrží DOCKUP_TOKEN až po schváleném triggeru.
4. Dockup: provede deployment a zaznamená auditní události.
5. Agent nebo operátor: interpretuje výsledek a navrhne obnovu.

Toto uspořádání zabrání tomu, aby prompt injection v nesouvisející úloze získal produkční credentials. Agent přitom může pipeline stále rozumět, protože příkazy a očekávaný JSON jsou uložené v repository, zatímco hodnota secretu zůstává mimo něj.

Pro deploymenty spouštěné přímo agentem injectujte token do konkrétního procesu Claude Code nebo Codex a nainstalujte bundled skill:

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

Skill instruuje oba agenty, aby používali neinteraktivní autentizaci, JSON, přesné zjišťování targetu, čekání na finální stav a confirmation gates.

Díky čemu je AI agent CI/CD opakovatelné a auditovatelné?

Opakovatelnost začíná explicitním targetem. Uložte production/api jako chráněnou pipeline variable nebo jako literal schválený v review, ne jako název, který agent odvodí za běhu. Před prvním zápisem ověřte účet.

Idempotence vyžaduje odlišný přístup podle typu operace:

• Čtení identity, statusu, logů a historie lze bezpečně opakovat.
• Vytváření služby musí začít zjištěním targetu, aby retry nevytvořil duplicitu.
• Opakovaný deployment vytvoří další produkční událost a měl by být zaznamenán.
• Změny environmentu jsou mutace a vyžadují nový deployment.
• Destrukce a pruning nesmí být automatickými cíli pro retry.

Po deploymentu shromážděte důkazy z platformy:

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

Uptime se měří každou minutu a zahrnuje průměrnou i p95 response time. Auditní výstup propojí mutaci provedenou CI s pozdější kontrolou. Spotřeba CPU, RAM a disku se také měří každou minutu oproti zůstatku účtu; doporučený Pro plan stojí 20 USD měsíčně s kreditem na usage ve výši 20 USD.

Kompletní záznam pipeline obsahuje Git commit, Dockup target, deployment ID, časy začátku a dokončení, exit code, finální status a odkazy na build artifacts. Díky tomu je AI agent CI/CD release reprodukovatelný, i když původní session agenta už neexistuje.

Referenci Dockup CLI považujte za autoritu pro příkazy. Pokud potřebujete vytvořit repository před zapnutím CI, postupujte podle návodu Z Git repository do produkce.

Řiďte souběh a promotion mezi environmenty

Dvě úspěšné pipeline mohou přesto vytvořit nebezpečný release, pokud běží souběžně proti stejnému targetu. Použijte concurrency controls CI platformy, aby novější produkční job buď počkal na starší, nebo jej záměrně nahradil. Dockup pravdivě reportuje každý deployment, ale workflow repository musí rozhodnout, v jakém pořadí se zpracují překrývající se commity.

Mezi environmenty promujte stejný commit schválený v review, místo abyste znovu buildili nesledovaný lokální stav. Staging job může nasadit staging/api, spustit aplikační kontroly a poté předat řízení chráněnému produkčnímu jobu, který nasadí production/api. Tokeny a targety udržujte oddělené, aby staging agent omylem nepřekročil tuto hranici.

Definujte pravidla pro retry při timeoutech

deploy_timeout neznamená chybu ani úspěch. Znamená, že operace po uplynutí 900sekundového čekání stále běžela. Před retry zkontrolujte:

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

Pokud původní deployment později dosáhl úspěchu, slepý retry by vytvořil další release. Pokud selhal, načtěte build log. Pokud stále není ve finálním stavu a build je legitimně dlouhý, spusťte pozorování znovu s delším, zdokumentovaným timeoutem, místo abyste vytvářeli druhý deployment.

Toto rozlišení brání tomu, aby se AI agent CI/CD kvůli nejistotě způsobené sítí nebo časováním změnilo v generování duplicitních produkčních změn.

Zaznamenejte identitu deploymentu

Do CI summary zahrňte identitu Dockup účtu, target, commit SHA, deployment ID a finální status. Tento malý záznam umožní pozdějšímu operátorovi propojit běh pipeline s auditními událostmi Dockup, aniž by odhalil token.

Uveďte workflow do produkce

Nainstalujte CLI na runneru, ověřte injectnutou identitu a jako gate pipeline použijte finální exit status procesu, nikoli logový řádek vypadající jako úspěch.

npm install -g dockup-cli
dockup skill install

První příkaz nainstaluje CLI. Druhý nainstaluje odpovídající Dockup skill pro Claude Code a Codex. Začněte zdarma na app.dockup.ai.

FAQ

Co je DOCKUP_TOKEN?

DOCKUP_TOKEN je autentizační cesta založená na environment variable pro session Dockup CLI, které nemohou dokončit interaktivní přihlášení v prohlížeči, například CI runnery, containery a AI agenti.

Přepisuje DOCKUP_TOKEN lokální konfigurační soubor Dockup?

Ano. Environment token má přednost a dockup whoami --json vrací aktivní zdroj tokenu.

Jak CI job pozná, že deployment Dockup selhal?

Spusťte dockup deploy s --wait a --json. Při selhání nebo timeoutu deploye příkaz skončí s nenulovým exit code a strukturovaným chybovým kódem.

Mělo by CI workflow při debuggingu vypsat deployment token?

Ne. Uchovávejte jej v CI secret store, vyhněte se shell tracingu a výpisům prostředí a zpřístupněte jej pouze deployment stepu.

Mohou Claude Code nebo Codex používat stejnou autentizační cestu CI?

Ano. Oba mohou používat DOCKUP_TOKEN a bundled Dockup skill, který je učí stejná pravidla pro JSON, zjišťování targetu, čekání a potvrzování.