AI Agent CI/CD with DOCKUP_TOKEN

AI agent CI/CD succeeds only when authentication and deployment behave correctly without a person at the terminal. Browser login, copied one-time codes, and prose-only status messages are incompatible with an unattended runner. Dockup supports the non-interactive path through DOCKUP_TOKEN, structured JSON, and deploy commands that return a real failure exit code.

This guide builds a pipeline contract that Claude Code, Codex, a shell script, or a conventional CI job can all use. The same rules apply: inject the token at runtime, verify identity, discover or specify the exact target, wait for a terminal result, and preserve diagnostics on failure.

Why does AI agent CI/CD need non-interactive authentication?

Interactive dockup login opens an authentication page and waits for a token. That is appropriate for a developer workstation, but a containerized runner may have no browser, no persistent home directory, and no person available to paste anything.

DOCKUP_TOKEN solves that boundary:

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

The environment variable takes precedence over ~/.dockup/config.json. whoami reports tokenSource, so the pipeline can prove that it is using the intended injected credential rather than an old config file left on a self-hosted runner.

Do not run dockup login -t "$DOCKUP_TOKEN" in CI unless there is a specific reason to persist a config file. Supplying the environment variable directly keeps the credential scoped to the process and avoids writing it to the runner’s home directory.

The pipeline must never echo the token. Disable shell tracing around secret-bearing commands, avoid printing the full environment, and use the CI platform’s masked secret facility.

How should DOCKUP_TOKEN be stored and scoped?

Store the token as an encrypted repository, environment, or organization secret. Prefer an environment-level secret for production because it can be combined with branch restrictions and manual approvals provided by the CI platform.

A secure token policy answers five questions:

Question	Recommended answer
Where is the token stored?	CI encrypted secret store
When is it exposed?	Only in the deployment job
Which branches can use it?	Protected production branches
Who can change the workflow?	Reviewed maintainers
How is use reviewed?	Dockup audit log plus CI job history

Dockup also supports permissioned API keys. List the available permission names before creating a narrowly scoped key:

dockup keys permissions --json

Choose only exact permission names returned by the platform, then create the key through the permissioned API-key workflow. Capture the generated key securely during creation and store it immediately and do not include it in an issue, pull request, or agent transcript; a deployment job should not inherit broad account administration simply because a developer token already has it.

The AI agent production guardrails article provides a broader permission ladder.

How do you build a deployment pipeline that waits for truth?

Install the CLI in the job, verify identity, then deploy with --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

The important part is not the CI vendor. It is the command contract. dockup deploy ... --wait --json exits 0 only when the deployment reaches success. The default timeout is 900 seconds. A failed build returns a non-zero exit with deploy_failed; a non-terminal operation at the timeout returns deploy_timeout.

Because the process exits non-zero, the runner marks the step and job as failed. No log scraping is required.

For a linked repository that should push its current branch and deploy, dockup push --json waits by default. In a CI job that has already received a Git push event, an explicit dockup deploy <target> is often clearer because it avoids pushing from the runner.

How should a pipeline capture logs and error codes?

Preserve the JSON deployment result as an artifact or job output, but avoid allowing a redirection to hide the exit status. A shell pattern can capture both:

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

The pipeline exits with the original deploy status. Build logs are collected only after failure. Runtime logs should be collected when the image built but the application later crashes:

dockup logs production/api --json

For live build visibility, follow mode emits NDJSON:

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

The stream terminates when the deployment does, and failure remains a non-zero process result. The detailed diagnostic sequence is covered in build and runtime log debugging.

A pipeline should branch on codes, not message fragments:

Code	Pipeline response
not_logged_in	Fail immediately; secret injection is broken
no_target	Fail; target configuration is invalid
deploy_trigger_failed	Fail before waiting; inspect returned error
deploy_failed	Upload build logs and fail
deploy_timeout	Mark uncertain; inspect status before retry
needs_confirm	Stop; a destructive step lacks approval

How can an agent participate without weakening CI security?

An agent can prepare code, update a reviewed workflow, interpret JSON, and summarize a failed build. It does not need unrestricted access to the production token in every coding session.

Separate the roles:

1. Development agent: edits code and tests locally.
2. Review process: validates changes to deployment configuration.
3. CI runner: receives DOCKUP_TOKEN only after the approved trigger.
4. Dockup: executes the deployment and records audit events.
5. Agent or operator: interprets the result and proposes recovery.

This arrangement prevents a prompt injection in an unrelated task from obtaining production credentials. The agent can still understand the pipeline because the commands and expected JSON are committed, while the secret value remains outside the repository.

For direct agent-run deployments, inject the token into the specific Claude Code or Codex process and install the bundled skill:

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

The skill instructs both agents to use non-interactive authentication, JSON, exact target discovery, terminal-state waiting, and confirmation gates.

What makes AI agent CI/CD repeatable and auditable?

Repeatability begins with an explicit target. Store production/api as a protected pipeline variable or a reviewed literal, not as a name the agent derives at runtime. Validate the account before the first write.

Idempotency requires different treatment by operation:

• Reading identity, status, logs, and history is safe to repeat.
• Service creation must begin with target discovery so retries do not create a duplicate.
• Deploying again creates another production event and should be recorded.
• Environment changes are mutations and require a redeploy.
• Destruction and pruning must not be automatic retry targets.

After deployment, collect platform evidence:

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

Uptime is measured every minute and includes average and p95 response time. Audit output connects the CI mutation with later review. CPU, RAM, and disk consumption are also measured per minute against the account balance; the recommended Go plan is $20 per month with $20 usage credit.

A complete pipeline record includes the Git commit, Dockup target, deployment ID, start and finish timestamps, exit code, terminal status, and links to build artifacts. This makes an AI agent CI/CD release reproducible even when the original agent session is gone.

The Dockup CLI reference should be treated as the command authority. For repository creation before CI is enabled, follow Git repository to production.

Control concurrency and environment promotion

Two successful pipelines can still create an unsafe release if they run concurrently against the same target. Use the CI platform’s concurrency controls so a newer production job either waits for or deliberately replaces an older one. Dockup will truthfully report each deployment, but the repository workflow must decide how overlapping commits are ordered.

Promote the same reviewed commit between environments rather than rebuilding an untracked local state. A staging job can deploy staging/api, run application checks, and then allow a protected production job to deploy production/api. Keep tokens and targets distinct so a staging agent cannot cross the boundary accidentally.

Define a retry policy for timeouts

deploy_timeout does not mean failure and does not mean success. It means the operation was still running when the 900-second wait ended. Before retrying, inspect:

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

If the original deployment later reached success, a blind retry would create another release. If it failed, collect the build log. If it remains non-terminal and the build is legitimately long, rerun the observation with a larger documented timeout rather than creating a second deployment.

This distinction keeps AI agent CI/CD from turning network or timing uncertainty into duplicate production changes.

Record the deployment identity

Include the Dockup account identity, target, commit SHA, deployment ID, and terminal status in the CI summary. This small record lets a later operator connect the pipeline run with Dockup audit events without exposing the token.

Put the workflow into production

Install the CLI in the runner, verify the injected identity, and make the terminal exit status—not a success-looking log line—the pipeline gate.

npm install -g dockup-cli
dockup skill install

The first command installs the CLI. The second installs the matching Dockup skill for Claude Code and Codex. Start free at app.dockup.ai.

FAQ

What is DOCKUP_TOKEN?

DOCKUP_TOKEN is the environment-based authentication path for Dockup CLI sessions that cannot complete interactive browser login, including CI runners, containers, and AI agents.

Does DOCKUP_TOKEN override a local Dockup config file?

Yes. The environment token takes precedence, and dockup whoami --json reports the active token source.

How does a CI job know a Dockup deployment failed?

Run dockup deploy with --wait and --json. The command exits non-zero with a structured failure code when the deploy fails or times out.

Should a CI workflow print the deployment token for debugging?

No. Keep it in the CI secret store, avoid shell tracing and environment dumps, and expose it only to the deployment step.

Can Claude Code or Codex use the same CI authentication path?

Yes. Both can use DOCKUP_TOKEN and the bundled Dockup skill, which teaches the same JSON, target-discovery, wait, and confirmation rules.