AI-agent-CI/CD met DOCKUP_TOKEN

AI-agent-CI/CD werkt alleen wanneer authenticatie en deployment correct functioneren zonder dat iemand achter de terminal zit. Browserlogin, handmatig gekopieerde eenmalige codes en statusberichten die alleen uit tekst bestaan, zijn niet geschikt voor een unattended runner. Dockup ondersteunt de non-interactive route via DOCKUP_TOKEN, gestructureerde JSON en deploy-opdrachten die een echte failure exit code retourneren.

In deze handleiding bouwen we een pipelinecontract dat Claude Code, Codex, een shellscript of een conventionele CI-job allemaal kunnen gebruiken. Dezelfde regels gelden: injecteer het token tijdens runtime, verifieer de identiteit, vind het exacte target of geef het expliciet op, wacht op een terminalresultaat en bewaar diagnostische informatie bij fouten.

Waarom heeft AI-agent-CI/CD non-interactive authenticatie nodig?

Interactieve dockup login opent een authenticatiepagina en wacht op een token. Dat is geschikt voor een developer workstation, maar een containerized runner heeft mogelijk geen browser, geen persistente home directory en niemand die iets kan plakken.

DOCKUP_TOKEN lost die grens op:

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

De environmentvariabele heeft voorrang op ~/.dockup/config.json. whoami rapporteert tokenSource, zodat de pipeline kan aantonen dat de bedoelde geïnjecteerde credential wordt gebruikt en niet een oud configuratiebestand dat op een self-hosted runner is achtergebleven.

Voer in CI geen dockup login -t "$DOCKUP_TOKEN" uit, tenzij er een specifieke reden is om een configuratiebestand te bewaren. Door de environmentvariabele rechtstreeks te gebruiken, blijft de credential beperkt tot het proces en voorkom je dat deze naar de home directory van de runner wordt geschreven.

De pipeline mag het token nooit echoën. Schakel shell tracing uit rond opdrachten die secrets bevatten, voorkom dat de volledige environment wordt afgedrukt en gebruik de masked-secretfunctie van het CI-platform.

Hoe moeten DOCKUP_TOKEN en de scope ervan worden beheerd?

Sla het token op als een encrypted repository-, environment- of organization-secret. Geef voor production de voorkeur aan een environment-level secret, omdat je dit kunt combineren met branch restrictions en manual approvals die door het CI-platform worden aangeboden.

Een veilig tokenbeleid beantwoordt vijf vragen:

Vraag	Aanbevolen antwoord
Waar wordt het token opgeslagen?	Encrypted secret store van CI
Wanneer wordt het beschikbaar gesteld?	Alleen in de deploymentjob
Welke branches kunnen het gebruiken?	Beschermde production-branches
Wie kan de workflow wijzigen?	Beoordeelde maintainers
Hoe wordt het gebruik gecontroleerd?	Dockup-auditlog plus CI-jobgeschiedenis

Dockup ondersteunt ook API keys met permissies. Bekijk eerst de beschikbare permission names voordat je een key met een beperkte scope aanmaakt:

dockup keys permissions --json

Kies uitsluitend exacte permission names die door het platform worden geretourneerd en maak de key vervolgens aan via de workflow voor API keys met permissies. Leg de gegenereerde key tijdens het aanmaken veilig vast en sla deze direct op; neem de key niet op in een issue, pull request of agenttranscript. Een deploymentjob mag geen brede accountadministratie erven alleen omdat een developertoken daar al toegang toe heeft.

Het artikel AI-agent production guardrails biedt een bredere permissieladder.

Hoe bouw je een deploymentpipeline die op de werkelijke uitkomst wacht?

Installeer de CLI in de job, verifieer de identiteit en deploy vervolgens met --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

Het belangrijkste onderdeel is niet de CI-leverancier, maar het commandocontract. dockup deploy ... --wait --json eindigt alleen met exitcode 0 wanneer de deployment succesvol is afgerond. De standaardtimeout is 900 seconden. Een mislukte build retourneert een non-zero exit met deploy_failed; een bewerking die bij het verlopen van de timeout nog niet terminaal is, retourneert deploy_timeout.

Omdat het proces eindigt met een non-zero exitcode, markeert de runner de step en job als mislukt. Het uitlezen van logs is niet nodig.

Voor een linked repository die de huidige branch moet pushen en deployen, wacht dockup push --json standaard. In een CI-job die al een Git push-event heeft ontvangen, is een expliciete dockup deploy <target> vaak duidelijker, omdat je daarmee voorkomt dat de runner zelf pusht.

Hoe moet een pipeline logs en foutcodes vastleggen?

Bewaar het JSON-resultaat van de deployment als artifact of job-output, maar voorkom dat een redirect de exitstatus verbergt. Met een shellpatroon kun je beide vastleggen:

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

De pipeline eindigt met de oorspronkelijke deploystatus. Buildlogs worden alleen na een fout verzameld. Runtimelogs moeten worden verzameld wanneer de image wel is gebouwd, maar de applicatie later crasht:

dockup logs production/api --json

Voor live inzicht in de build geeft de follow-modus NDJSON uit:

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

De stream stopt wanneer de deployment stopt, en een fout blijft resulteren in een non-zero procesresultaat. De gedetailleerde diagnostische volgorde wordt behandeld in build- en runtimelog-debugging.

Een pipeline moet op codes vertakken, niet op fragmenten uit berichten:

Code	Reactie van de pipeline
not_logged_in	Direct mislukken; secretinjectie werkt niet
no_target	Mislukken; de targetconfiguratie is ongeldig
deploy_trigger_failed	Mislukken vóór het wachten; controleer de geretourneerde fout
deploy_failed	Buildlogs uploaden en mislukken
deploy_timeout	Onzeker markeren; controleer de status vóór een retry
needs_confirm	Stoppen; voor een destructieve stap ontbreekt goedkeuring

Hoe kan een agent deelnemen zonder de CI-beveiliging te verzwakken?

Een agent kan code voorbereiden, een beoordeelde workflow bijwerken, JSON interpreteren en een mislukte build samenvatten. De agent heeft niet tijdens elke coding-sessie onbeperkte toegang tot het production-token nodig.

Scheid de rollen:

1. Development-agent: bewerkt code en tests lokaal.
2. Reviewproces: valideert wijzigingen in de deploymentconfiguratie.
3. CI-runner: ontvangt DOCKUP_TOKEN pas na de goedgekeurde trigger.
4. Dockup: voert de deployment uit en registreert audit-events.
5. Agent of operator: interpreteert het resultaat en stelt herstel voor.

Deze opzet voorkomt dat een prompt injection in een niet-gerelateerde taak production-credentials buitmaakt. De agent kan de pipeline nog steeds begrijpen, omdat de opdrachten en verwachte JSON in de repository zijn vastgelegd, terwijl de secretwaarde buiten de repository blijft.

Voor deployments die rechtstreeks door een agent worden uitgevoerd, injecteer je het token in het specifieke Claude Code- of Codex-proces en installeer je de gebundelde skill:

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

De skill instrueert beide agents om non-interactive authenticatie, JSON, het exact bepalen van het target, wachten op een terminalstatus en confirmation gates te gebruiken.

Wat maakt AI-agent-CI/CD herhaalbaar en controleerbaar?

Herhaalbaarheid begint met een expliciet target. Sla production/api op als een protected pipeline variable of een letterlijk vastgelegde, beoordeelde waarde, niet als een naam die de agent tijdens runtime afleidt. Valideer het account vóór de eerste schrijfactie.

Idempotency vereist per bewerking een andere aanpak:

• Het opnieuw uitvoeren van identity, status, logs en history lezen is veilig.
• Het aanmaken van een service moet beginnen met target discovery, zodat retries geen duplicaat aanmaken.
• Opnieuw deployen creëert een nieuw production-event en moet worden geregistreerd.
• Wijzigingen in de environment zijn mutaties en vereisen een nieuwe deployment.
• Destruction en pruning mogen geen automatische retry-doelen zijn.

Verzamel na de deployment bewijs uit het platform:

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

Uptime wordt elke minuut gemeten en bevat de gemiddelde en p95-responstijd. Auditoutput koppelt de CI-mutatie aan een latere review. CPU-, RAM- en schijfverbruik worden eveneens elke minuut afgezet tegen het accountsaldo; het aanbevolen Pro-plan kost $20 per maand met $20 gebruikstegoed.

Een volledig pipelinerecord bevat de Git-commit, het Dockup-target, de deployment-ID, begin- en eindtijdstempels, exitcode, terminalstatus en links naar buildartifacts. Hierdoor blijft een AI-agent-CI/CD-release reproduceerbaar, zelfs wanneer de oorspronkelijke agentsessie niet meer bestaat.

De Dockup CLI-referentie moet als autoriteit voor opdrachten worden beschouwd. Volg voor het aanmaken van een repository voordat CI wordt ingeschakeld Van Git-repository naar production.

Beheer concurrency en promotie tussen omgevingen

Twee succesvolle pipelines kunnen nog steeds een onveilige release veroorzaken wanneer ze gelijktijdig hetzelfde target gebruiken. Gebruik de concurrency-controls van het CI-platform, zodat een nieuwere production-job wacht op een oudere job of deze bewust vervangt. Dockup rapporteert elke deployment waarheidsgetrouw, maar de repositoryworkflow moet bepalen hoe overlappende commits worden geordend.

Promoot dezelfde beoordeelde commit tussen omgevingen in plaats van een niet-gevolgde lokale toestand opnieuw te bouwen. Een staging-job kan staging/api deployen, application checks uitvoeren en vervolgens een beschermde production-job toestaan om production/api te deployen. Houd tokens en targets gescheiden, zodat een staging-agent niet per ongeluk de grens kan overschrijden.

Definieer een retrybeleid voor timeouts

deploy_timeout betekent niet dat de deployment is mislukt en ook niet dat deze is geslaagd. Het betekent dat de bewerking nog liep toen het wachten na 900 seconden eindigde. Controleer vóór een retry:

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

Als de oorspronkelijke deployment later alsnog succesvol is afgerond, zou een blinde retry een tweede release aanmaken. Als de deployment is mislukt, verzamel je de buildlog. Als de deployment niet-terminaal blijft en de build legitiem lang duurt, observeer je opnieuw met een grotere, gedocumenteerde timeout in plaats van een tweede deployment aan te maken.

Dit onderscheid voorkomt dat AI-agent-CI/CD netwerk- of timingonzekerheid omzet in dubbele production-wijzigingen.

Leg de deploymentidentiteit vast

Neem de Dockup-accountidentiteit, het target, de commit-SHA, de deployment-ID en de terminalstatus op in het CI-overzicht. Met dit kleine record kan een latere operator de pipeline-run koppelen aan Dockup-audit-events zonder het token bloot te leggen.

Zet de workflow in production

Installeer de CLI op de runner, verifieer de geïnjecteerde identiteit en maak van de terminalstatus — niet van een logregel die op succes lijkt — de gate van de pipeline.

npm install -g dockup-cli
dockup skill install

De eerste opdracht installeert de CLI. De tweede installeert de bijbehorende Dockup-skill voor Claude Code en Codex. Begin gratis op app.dockup.ai.

Veelgestelde vragen

Wat is DOCKUP_TOKEN?

DOCKUP_TOKEN is de environmentgebaseerde authenticatieroute voor Dockup CLI-sessies die geen interactieve browserlogin kunnen voltooien, waaronder CI-runners, containers en AI-agents.

Overschrijft DOCKUP_TOKEN een lokaal Dockup-configuratiebestand?

Ja. Het environmenttoken heeft voorrang en dockup whoami --json rapporteert de actieve tokenbron.

Hoe weet een CI-job dat een Dockup-deployment is mislukt?

Voer dockup deploy uit met --wait en --json. De opdracht eindigt met een non-zero exitcode en een gestructureerde foutcode wanneer de deployment mislukt of een timeout optreedt.

Moet een CI-workflow het deploymenttoken afdrukken voor debugging?

Nee. Bewaar het in de CI-secretstore, vermijd shell tracing en environmentdumps en stel het alleen beschikbaar aan de deploymentstep.

Kunnen Claude Code of Codex dezelfde CI-authenticatieroute gebruiken?

Ja. Beide kunnen DOCKUP_TOKEN en de gebundelde Dockup-skill gebruiken. Die leert dezelfde regels voor JSON, target discovery, wachten en confirmation.