CI/CD de agentes de IA com DOCKUP_TOKEN

O CI/CD de agentes de IA só funciona quando a autenticação e o deploy se comportam corretamente sem uma pessoa no terminal. Login pelo navegador, códigos de uso único copiados manualmente e mensagens de status compostas apenas por texto são incompatíveis com um runner não supervisionado. O Dockup oferece o fluxo não interativo por meio de DOCKUP_TOKEN, JSON estruturado e comandos de deploy que retornam um exit code de falha real.

Este guia define um contrato de pipeline que pode ser usado por Claude Code, Codex, um shell script ou um job de CI convencional. As mesmas regras se aplicam: injete o token em runtime, verifique a identidade, descubra ou especifique o target exato, aguarde um resultado terminal e preserve os diagnósticos em caso de falha.

Por que o CI/CD de agentes de IA precisa de autenticação não interativa?

O dockup login interativo abre uma página de autenticação e aguarda um token. Isso é adequado para a workstation de um desenvolvedor, mas um runner em container pode não ter navegador, diretório home persistente ou uma pessoa disponível para colar qualquer informação.

O DOCKUP_TOKEN resolve essa fronteira:

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

A variável de ambiente tem precedência sobre ~/.dockup/config.json. O whoami informa tokenSource, permitindo que o pipeline comprove que está usando a credencial injetada esperada, em vez de um arquivo de configuração antigo deixado em um runner self-hosted.

Não execute dockup login -t "$DOCKUP_TOKEN" no CI, a menos que exista um motivo específico para persistir um arquivo de configuração. Fornecer a variável de ambiente diretamente mantém a credencial restrita ao processo e evita gravá-la no diretório home do runner.

O pipeline nunca deve exibir o token. Desative o tracing do shell ao redor de comandos que contenham secrets, evite imprimir o ambiente completo e use o recurso de secrets mascarados da plataforma de CI.

Como o DOCKUP_TOKEN deve ser armazenado e ter seu escopo definido?

Armazene o token como um secret criptografado do repositório, ambiente ou organização. Prefira um secret no nível do ambiente para produção, pois ele pode ser combinado com restrições de branch e aprovações manuais oferecidas pela plataforma de CI.

Uma política segura de tokens responde a cinco perguntas:

Pergunta	Resposta recomendada
Onde o token é armazenado?	Secret store criptografado do CI
Quando ele é exposto?	Somente no job de deploy
Quais branches podem usá-lo?	Branches de produção protegidas
Quem pode alterar o workflow?	Maintainers responsáveis pela revisão
Como o uso é revisado?	Log de auditoria do Dockup e histórico do job de CI

O Dockup também oferece suporte a API keys com permissões. Liste os nomes de permissões disponíveis antes de criar uma key com escopo restrito:

dockup keys permissions --json

Escolha apenas os nomes exatos de permissões retornados pela plataforma e crie a key por meio do fluxo de API keys com permissões. Capture a key gerada com segurança durante a criação, armazene-a imediatamente e não a inclua em uma issue, pull request ou transcrição do agente; um job de deploy não deve herdar amplos privilégios de administração da conta apenas porque um token de desenvolvedor já os possui.

O artigo guardrails de produção para agentes de IA apresenta uma escala de permissões mais abrangente.

Como criar um pipeline de deploy que aguarde a confirmação do resultado?

Instale a CLI no job, verifique a identidade e faça o deploy com --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

A parte importante não é o fornecedor de CI. É o contrato do comando. dockup deploy ... --wait --json sai com 0 somente quando o deploy alcança o sucesso. O timeout padrão é de 900 segundos. Um build com falha retorna um exit code diferente de zero com deploy_failed; uma operação que não chega a um estado terminal dentro do timeout retorna deploy_timeout.

Como o processo sai com um código diferente de zero, o runner marca o step e o job como falhos. Não é necessário fazer parsing dos logs.

Para um repositório vinculado que deve enviar a branch atual e fazer o deploy, dockup push --json aguarda por padrão. Em um job de CI que já recebeu um evento de push do Git, um dockup deploy <target> explícito costuma ser mais claro, pois evita fazer push a partir do runner.

Como um pipeline deve capturar logs e códigos de erro?

Preserve o resultado JSON do deploy como um artifact ou output do job, mas evite que um redirecionamento oculte o exit status. Um padrão de shell pode capturar ambos:

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

O pipeline sai com o status original do deploy. Os build logs são coletados somente após uma falha. Os runtime logs devem ser coletados quando a imagem tiver sido criada, mas a aplicação apresentar uma falha posteriormente:

dockup logs production/api --json

Para acompanhar o build em tempo real, o modo follow emite NDJSON:

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

O stream é encerrado quando o deploy termina, e a falha continua resultando em um processo com código diferente de zero. A sequência detalhada de diagnóstico é abordada em debugging de build e runtime logs.

Um pipeline deve tomar decisões com base nos códigos, não em fragmentos de mensagens:

Código	Resposta do pipeline
not_logged_in	Falhar imediatamente; a injeção do secret está quebrada
no_target	Falhar; a configuração do target é inválida
deploy_trigger_failed	Falhar antes de aguardar; inspecionar o erro retornado
deploy_failed	Fazer upload dos build logs e falhar
deploy_timeout	Marcar como incerto; verificar o status antes de tentar novamente
needs_confirm	Parar; um step destrutivo não tem aprovação

Como um agente pode participar sem reduzir a segurança do CI?

Um agente pode preparar código, atualizar um workflow revisado, interpretar JSON e resumir um build com falha. Ele não precisa de acesso irrestrito ao token de produção em todas as sessões de desenvolvimento.

Separe as funções:

1. Agente de desenvolvimento: edita código e executa testes localmente.
2. Processo de revisão: valida alterações na configuração de deploy.
3. Runner de CI: recebe DOCKUP_TOKEN somente após o trigger aprovado.
4. Dockup: executa o deploy e registra eventos de auditoria.
5. Agente ou operador: interpreta o resultado e propõe a recuperação.

Essa organização impede que uma prompt injection em uma tarefa não relacionada obtenha credenciais de produção. O agente ainda pode entender o pipeline porque os comandos e o JSON esperado estão versionados, enquanto o valor do secret permanece fora do repositório.

Para fazer deploys executados diretamente pelo agente, injete o token no processo específico do Claude Code ou Codex e instale a skill incluída:

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

A skill orienta ambos os agentes a usar autenticação não interativa, JSON, descoberta do target exato, espera pelo estado terminal e gates de confirmação.

O que torna o CI/CD de agentes de IA repetível e auditável?

A repetibilidade começa com um target explícito. Armazene production/api como uma variável protegida do pipeline ou um literal revisado, e não como um nome que o agente deriva em runtime. Valide a conta antes da primeira operação de escrita.

A idempotência exige tratamentos diferentes conforme a operação:

• Ler identidade, status, logs e histórico é seguro para repetir.
• A criação de serviços deve começar pela descoberta do target, para que as tentativas novamente não criem duplicatas.
• Fazer deploy novamente cria outro evento de produção e deve ser registrado.
• Alterações de ambiente são mutações e exigem um novo deploy.
• Destruição e pruning não devem ser alvos de retry automático.

Após o deploy, colete evidências da plataforma:

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

O uptime é medido a cada minuto e inclui o tempo médio de resposta e o p95. O output de auditoria conecta a mutação do CI às revisões posteriores. O consumo de CPU, RAM e disco também é medido a cada minuto em relação ao saldo da conta; o plano Pro recomendado custa US$ 20 por mês e inclui US$ 20 em créditos de uso.

Um registro completo do pipeline inclui o commit do Git, o target do Dockup, o ID do deploy, os timestamps de início e término, o exit code, o status terminal e links para os artifacts do build. Isso torna uma versão de CI/CD de agentes de IA reproduzível mesmo quando a sessão original do agente já não existe.

A referência da Dockup CLI deve ser considerada a autoridade sobre os comandos. Para criar um repositório antes de habilitar o CI, siga Do repositório Git à produção.

Controle a concorrência e a promoção entre ambientes

Dois pipelines bem-sucedidos ainda podem criar uma release insegura se forem executados simultaneamente no mesmo target. Use os controles de concorrência da plataforma de CI para que um job de produção mais recente aguarde o anterior ou o substitua deliberadamente. O Dockup informará com precisão cada deploy, mas o workflow do repositório deve decidir como commits sobrepostos serão ordenados.

Promova o mesmo commit revisado entre os ambientes, em vez de fazer um novo build a partir de um estado local não rastreado. Um job de staging pode fazer deploy de staging/api, executar verificações da aplicação e, em seguida, permitir que um job de produção protegido faça deploy de production/api. Mantenha tokens e targets distintos para que um agente de staging não atravesse essa fronteira acidentalmente.

Defina uma política de retry para timeouts

deploy_timeout não significa falha nem sucesso. Significa que a operação ainda estava em execução quando a espera de 900 segundos terminou. Antes de tentar novamente, inspecione:

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

Se o deploy original tiver alcançado o sucesso posteriormente, uma nova tentativa às cegas criará outra release. Se ele tiver falhado, colete o build log. Se continuar sem estado terminal e o build for legitimamente longo, repita a observação com um timeout maior e documentado, em vez de criar um segundo deploy.

Essa distinção impede que o CI/CD de agentes de IA transforme incertezas de rede ou de tempo em alterações duplicadas na produção.

Registre a identidade do deploy

Inclua no resumo do CI a identidade da conta do Dockup, o target, o SHA do commit, o ID do deploy e o status terminal. Esse pequeno registro permite que um operador posterior conecte a execução do pipeline aos eventos de auditoria do Dockup sem expor o token.

Coloque o workflow em produção

Instale a CLI no runner, verifique a identidade injetada e faça do status de saída terminal — e não de uma linha de log que pareça indicar sucesso — o gate do pipeline.

npm install -g dockup-cli
dockup skill install

O primeiro comando instala a CLI. O segundo instala a skill correspondente do Dockup para Claude Code e Codex. Comece gratuitamente em app.dockup.ai.

FAQ

O que é DOCKUP_TOKEN?

DOCKUP_TOKEN é o mecanismo de autenticação baseado em ambiente para sessões da Dockup CLI que não podem concluir o login interativo pelo navegador, incluindo runners de CI, containers e agentes de IA.

O DOCKUP_TOKEN substitui um arquivo de configuração local do Dockup?

Sim. O token de ambiente tem precedência, e dockup whoami --json informa a origem ativa do token.

Como um job de CI sabe que um deploy do Dockup falhou?

Execute dockup deploy com --wait e --json. O comando sai com código diferente de zero e um código de falha estruturado quando o deploy falha ou atinge o timeout.

Um workflow de CI deve imprimir o token de deploy para debugging?

Não. Mantenha-o no secret store do CI, evite tracing do shell e dumps do ambiente e exponha-o somente ao step de deploy.

Claude Code ou Codex podem usar o mesmo mecanismo de autenticação do CI?

Sim. Ambos podem usar DOCKUP_TOKEN e a skill incluída do Dockup, que ensina as mesmas regras de JSON, descoberta de target, espera e confirmação.