CI/CD für KI-Agenten mit DOCKUP_TOKEN

CI/CD für KI-Agenten funktioniert nur dann zuverlässig, wenn Authentifizierung und Bereitstellung ohne eine Person am Terminal korrekt ablaufen. Browser-Login, kopierte Einmalcodes und reine Statusmeldungen in Textform sind mit einem unbeaufsichtigten Runner nicht kompatibel. Dockup unterstützt den nicht-interaktiven Ablauf über DOCKUP_TOKEN, strukturiertes JSON und Deploy-Befehle, die bei Fehlern tatsächlich einen entsprechenden Exit-Code zurückgeben.

Dieser Leitfaden definiert einen Pipeline-Vertrag, den Claude Code, Codex, ein Shell-Script oder ein herkömmlicher CI-Job verwenden können. Die Regeln sind immer gleich: Token zur Laufzeit injizieren, Identität überprüfen, das exakte Ziel ermitteln oder explizit angeben, auf ein finales Ergebnis warten und bei Fehlern die Diagnoseinformationen erhalten.

Warum benötigt CI/CD für KI-Agenten eine nicht-interaktive Authentifizierung?

Der interaktive Befehl dockup login öffnet eine Authentifizierungsseite und wartet auf einen Token. Das ist für eine Entwickler-Workstation geeignet, ein containerisierter Runner verfügt jedoch möglicherweise über keinen Browser, kein dauerhaftes Home-Verzeichnis und keine Person, die etwas einfügen kann.

DOCKUP_TOKEN löst diese Einschränkung:

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

Die Umgebungsvariable hat Vorrang vor ~/.dockup/config.json. whoami gibt tokenSource aus. Dadurch kann die Pipeline nachweisen, dass sie den vorgesehenen injizierten Zugang verwendet und nicht etwa eine alte Konfigurationsdatei, die auf einem selbst gehosteten Runner zurückgeblieben ist.

Führe in CI nicht dockup login -t "$DOCKUP_TOKEN" aus, sofern kein konkreter Grund dafür besteht, eine Konfigurationsdatei dauerhaft zu speichern. Wenn du die Umgebungsvariable direkt übergibst, bleibt das Credential auf den Prozess beschränkt und wird nicht in das Home-Verzeichnis des Runners geschrieben.

Die Pipeline darf den Token niemals ausgeben. Deaktiviere das Shell-Tracing rund um Befehle, die Secrets enthalten, gib nicht die vollständige Umgebung aus und verwende die Maskierungsfunktion der CI-Plattform für Secrets.

Wie sollte DOCKUP_TOKEN gespeichert und eingeschränkt werden?

Speichere den Token als verschlüsseltes Repository-, Umgebungs- oder Organisations-Secret. Für die Produktion empfiehlt sich ein Secret auf Umgebungsebene, da es mit Branch-Beschränkungen und manuellen Freigaben der CI-Plattform kombiniert werden kann.

Eine sichere Token-Richtlinie beantwortet fünf Fragen:

Frage	Empfohlene Antwort
Wo wird der Token gespeichert?	Verschlüsselter CI-Secret-Speicher
Wann wird er bereitgestellt?	Nur im Deployment-Job
Welche Branches dürfen ihn verwenden?	Geschützte Produktions-Branches
Wer darf den Workflow ändern?	Überprüfte Maintainer
Wie wird die Nutzung überprüft?	Dockup-Audit-Log plus CI-Job-Verlauf

Dockup unterstützt außerdem API-Keys mit Berechtigungen. Liste vor dem Erstellen eines möglichst eng eingeschränkten Keys die verfügbaren Berechtigungsnamen auf:

dockup keys permissions --json

Verwende ausschließlich die exakten Berechtigungsnamen, die von der Plattform zurückgegeben werden, und erstelle den Key anschließend über den Workflow für API-Keys mit Berechtigungen. Sichere den beim Erstellen generierten Key sofort zuverlässig. Nimm ihn nicht in ein Issue, einen Pull Request oder ein Agent-Transkript auf. Ein Deployment-Job sollte nicht allein deshalb umfassende Kontoadministrationsrechte erhalten, weil ein Entwickler-Token bereits darüber verfügt.

Der Artikel Sicherheitsleitplanken für KI-Agenten in der Produktion beschreibt eine umfassendere Berechtigungsabstufung.

Wie erstellt man eine Deployment-Pipeline, die auf die tatsächliche Wahrheit wartet?

Installiere die CLI im Job, überprüfe die Identität und deploye anschließend mit --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

Entscheidend ist nicht der CI-Anbieter, sondern der Befehlsvertrag. dockup deploy ... --wait --json beendet sich nur dann mit 0, wenn die Bereitstellung erfolgreich abgeschlossen ist. Das Standard-Timeout beträgt 900 Sekunden. Ein fehlgeschlagener Build gibt einen Exit-Code ungleich null mit deploy_failed zurück; erreicht der Vorgang beim Timeout keinen finalen Status, wird deploy_timeout zurückgegeben.

Da der Prozess mit einem Exit-Code ungleich null endet, markiert der Runner den Schritt und den Job als fehlgeschlagen. Das Auswerten von Logs ist nicht erforderlich.

Bei einem verknüpften Repository, das seinen aktuellen Branch pushen und deployen soll, wartet dockup push --json standardmäßig. In einem CI-Job, der bereits ein Git-Push-Event erhalten hat, ist ein explizites dockup deploy <target> oft übersichtlicher, da dadurch ein Push vom Runner vermieden wird.

Wie sollte eine Pipeline Logs und Fehlercodes erfassen?

Bewahre das JSON-Ergebnis des Deployments als Artefakt oder Job-Output auf. Verhindere jedoch, dass eine Umleitung den Exit-Status verbirgt. Mit diesem Shell-Muster lassen sich beides erfassen:

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

Die Pipeline wird mit dem ursprünglichen Deployment-Status beendet. Build-Logs werden erst nach einem Fehler gesammelt. Runtime-Logs sollten erfasst werden, wenn das Image erfolgreich gebaut wurde, die Anwendung später jedoch abstürzt:

dockup logs production/api --json

Für die Live-Anzeige des Build-Fortschritts gibt der Follow-Modus NDJSON aus:

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

Der Stream endet, sobald die Bereitstellung abgeschlossen ist, und ein Fehler führt weiterhin zu einem Exit-Code ungleich null. Die ausführliche Diagnoseabfolge wird unter Build- und Runtime-Logs debuggen beschrieben.

Eine Pipeline sollte anhand von Codes verzweigen, nicht anhand von Fragmenten in Fehlermeldungen:

Code	Reaktion der Pipeline
not_logged_in	Sofort fehlschlagen; die Secret-Injektion ist fehlerhaft
no_target	Fehlschlagen; die Zielkonfiguration ist ungültig
deploy_trigger_failed	Vor dem Warten fehlschlagen; den zurückgegebenen Fehler prüfen
deploy_failed	Build-Logs hochladen und fehlschlagen
deploy_timeout	Status unklar markieren; Status vor einem erneuten Versuch prüfen
needs_confirm	Anhalten; für einen destruktiven Schritt fehlt die Freigabe

Wie kann ein Agent teilnehmen, ohne die CI-Sicherheit zu schwächen?

Ein Agent kann Code vorbereiten, einen überprüften Workflow aktualisieren, JSON interpretieren und einen fehlgeschlagenen Build zusammenfassen. Er benötigt nicht in jeder Coding-Session uneingeschränkten Zugriff auf den Produktions-Token.

Trenne die Rollen:

1. Entwicklungsagent: bearbeitet Code und Tests lokal.
2. Review-Prozess: überprüft Änderungen an der Deployment-Konfiguration.
3. CI-Runner: erhält DOCKUP_TOKEN erst nach dem freigegebenen Trigger.
4. Dockup: führt die Bereitstellung aus und protokolliert Audit-Ereignisse.
5. Agent oder Operator: interpretiert das Ergebnis und schlägt eine Wiederherstellung vor.

Diese Struktur verhindert, dass eine Prompt-Injection in einer unabhängigen Aufgabe Produktions-Credentials erlangt. Der Agent kann die Pipeline trotzdem verstehen, weil die Befehle und das erwartete JSON im Repository versioniert sind, während der Secret-Wert außerhalb des Repositorys bleibt.

Für direkt von einem Agenten ausgeführte Deployments injiziere den Token in den jeweiligen Claude-Code- oder Codex-Prozess und installiere das gebündelte Skill:

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

Das Skill weist beide Agents an, nicht-interaktive Authentifizierung, JSON, die Ermittlung des exakten Ziels, das Warten auf einen finalen Status und Bestätigungsschranken zu verwenden.

Was macht CI/CD für KI-Agenten wiederholbar und revisionssicher?

Wiederholbarkeit beginnt mit einem expliziten Ziel. Speichere production/api als geschützte Pipeline-Variable oder als überprüftes Literal und nicht als Namen, den der Agent zur Laufzeit ableitet. Validiere das Konto vor dem ersten Schreibvorgang.

Idempotenz erfordert je nach Vorgang ein unterschiedliches Vorgehen:

• Das Lesen von Identität, Status, Logs und Verlauf kann sicher wiederholt werden.
• Die Erstellung eines Services muss mit der Ermittlung des Ziels beginnen, damit Wiederholungen kein Duplikat erzeugen.
• Ein erneutes Deployment erzeugt ein weiteres Produktionsevent und sollte protokolliert werden.
• Änderungen an der Umgebung sind Mutationen und erfordern ein erneutes Deployment.
• Zerstörung und Bereinigung dürfen keine automatischen Ziele für Wiederholungen sein.

Sammle nach dem Deployment Nachweise von der Plattform:

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

Die Uptime wird jede Minute gemessen und umfasst die durchschnittliche Antwortzeit sowie die p95-Antwortzeit. Die Audit-Ausgabe verbindet die CI-Mutation mit der späteren Überprüfung. Auch CPU-, RAM- und Festplattenverbrauch werden minütlich im Verhältnis zum Kontoguthaben gemessen. Der empfohlene Pro-Plan kostet 20 $ pro Monat und enthält ein Nutzungsguthaben von 20 $.

Ein vollständiger Pipeline-Eintrag umfasst den Git-Commit, das Dockup-Ziel, die Deployment-ID, Zeitstempel für Start und Ende, den Exit-Code, den finalen Status und Links zu Build-Artefakten. Dadurch bleibt ein CI/CD für KI-Agenten-Release reproduzierbar, auch wenn die ursprüngliche Agent-Session nicht mehr vorhanden ist.

Die Dockup-CLI-Referenz sollte als maßgebliche Quelle für Befehle behandelt werden. Informationen zur Erstellung eines Repositorys vor der Aktivierung von CI findest du unter Vom Git-Repository zur Produktion.

Parallelität und Promotion zwischen Umgebungen steuern

Zwei erfolgreiche Pipelines können trotzdem ein unsicheres Release erzeugen, wenn sie gleichzeitig auf dasselbe Ziel zugreifen. Verwende die Parallelitätskontrollen der CI-Plattform, damit ein neuerer Produktionsjob entweder auf einen älteren wartet oder ihn bewusst ersetzt. Dockup meldet jedes Deployment korrekt, aber der Repository-Workflow muss entscheiden, in welcher Reihenfolge überlappende Commits verarbeitet werden.

Promote denselben überprüften Commit zwischen Umgebungen, statt einen nicht versionierten lokalen Stand neu zu bauen. Ein Staging-Job kann staging/api deployen, Anwendungstests ausführen und anschließend einem geschützten Produktionsjob erlauben, production/api zu deployen. Halte Tokens und Ziele getrennt, damit ein Staging-Agent nicht versehentlich die Grenze überschreitet.

Eine Retry-Richtlinie für Timeouts definieren

deploy_timeout bedeutet weder Fehler noch Erfolg. Es bedeutet, dass der Vorgang nach Ablauf der 900-sekündigen Wartezeit noch lief. Prüfe vor einem erneuten Versuch:

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

Wenn das ursprüngliche Deployment später erfolgreich war, würde ein blindes Wiederholen ein weiteres Release erzeugen. Wenn es fehlgeschlagen ist, sammle das Build-Log. Wenn der Vorgang weiterhin keinen finalen Status erreicht hat und der Build berechtigterweise lange dauert, wiederhole die Beobachtung mit einem größeren, dokumentierten Timeout, statt ein zweites Deployment zu erstellen.

Diese Unterscheidung verhindert, dass CI/CD für KI-Agenten Netzwerk- oder Timing-Unsicherheit in doppelte Produktionsänderungen verwandelt.

Die Deployment-Identität protokollieren

Nimm die Identität des Dockup-Kontos, das Ziel, den Commit-SHA, die Deployment-ID und den finalen Status in die CI-Zusammenfassung auf. Dieser kleine Eintrag ermöglicht es einem späteren Operator, den Pipeline-Lauf mit Dockup-Audit-Ereignissen zu verknüpfen, ohne den Token offenzulegen.

Den Workflow in Produktion bringen

Installiere die CLI im Runner, überprüfe die injizierte Identität und mache den finalen Exit-Status des Prozesses – nicht eine Erfolg suggerierende Logzeile – zum Gate der Pipeline.

npm install -g dockup-cli
dockup skill install

Der erste Befehl installiert die CLI. Der zweite installiert das passende Dockup-Skill für Claude Code und Codex. Starte kostenlos unter app.dockup.ai.

FAQ

Was ist DOCKUP_TOKEN?

DOCKUP_TOKEN ist der umgebungsbasierte Authentifizierungsweg für Dockup-CLI-Sessions, die keinen interaktiven Browser-Login abschließen können, darunter CI-Runner, Container und KI-Agenten.

Überschreibt DOCKUP_TOKEN eine lokale Dockup-Konfigurationsdatei?

Ja. Der Umgebungs-Token hat Vorrang, und dockup whoami --json gibt die aktive Token-Quelle aus.

Woran erkennt ein CI-Job, dass ein Dockup-Deployment fehlgeschlagen ist?

Führe dockup deploy mit --wait und --json aus. Der Befehl endet mit einem Exit-Code ungleich null und einem strukturierten Fehlercode, wenn das Deployment fehlschlägt oder das Timeout erreicht.

Sollte ein CI-Workflow den Deployment-Token zur Fehlersuche ausgeben?

Nein. Bewahre ihn im CI-Secret-Speicher auf, vermeide Shell-Tracing und Ausgaben der Umgebung und stelle ihn nur dem Deployment-Schritt bereit.

Können Claude Code oder Codex denselben CI-Authentifizierungsweg verwenden?

Ja. Beide können DOCKUP_TOKEN und das gebündelte Dockup-Skill verwenden, das dieselben Regeln für JSON, Zielermittlung, Warten und Bestätigungen vermittelt.