Deploy do Codex: fluxo completo com Dockup

Um deploy do Codex deve terminar com evidências, não com suposições. O desafio prático não é pedir ao Codex para executar um comando de deploy; é fornecer ao agente uma interface que identifique o target exato, aguarde um estado terminal, devolva códigos de saída reais e exponha os detalhes da falha sem usar um browser.

O Dockup é a camada de deploy deste workflow. A CLI fornece ao Codex JSON estruturado em todos os comandos compatíveis, e a skill incluída ensina o agente a autenticar-se, descobrir serviços, fazer deploy, diagnosticar problemas e parar antes de operações destrutivas.

Como instalar a skill da CLI do Codex?

Instale a CLI globalmente e, em seguida, execute o instalador único da skill. Ele grava a skill canónica e cria links para ela no Claude Code e no Codex:

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

A skill canónica encontra-se em ~/.agents/skills/dockup/ e é ligada a ~/.codex/skills/. Ela é distribuída dentro de dockup-cli, por isso uma atualização normal altera o executável e as respetivas instruções em conjunto:

dockup update

Este acoplamento de versões é importante numa superfície de comandos extensa. Um agente nunca deve executar uma flag memorizada apenas porque ela apareceu num prompt antigo. O Codex deve usar a skill empacotada e a referência atual da Dockup CLI como autoridade para os comandos.

Para conhecer a lógica de design por trás das skills, consulte agent skills vs MCP.

Como é que o Codex se autentica sem um terminal interativo?

Uma sandbox ou um job de CI pode não conseguir concluir um login baseado em browser. Defina um token no ambiente do processo:

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

DOCKUP_TOKEN tem precedência sobre o ficheiro de configuração local. A resposta de whoami indica se a credencial ativa veio do ambiente ou da configuração, o que ajuda o Codex a diagnosticar o caso comum em que coexistem um token local obsoleto e um token de CI.

Trate o token como um secret de infraestrutura. Não o coloque em AGENTS.md, SKILL.md, no controlo de versões, em exemplos de comandos submetidos ao repositório ou na transcrição final do agente. Em CI, use o armazenamento de secrets encriptado da plataforma e exponha o valor apenas ao passo de deploy. O padrão não interativo completo é detalhado em CI/CD com DOCKUP_TOKEN.

Antes de conceder acesso de escrita ao Codex, defina o seu âmbito de permissões. Um âmbito inicial razoável inclui a descoberta de serviços, deploy, leitura de logs e verificações de estado. A eliminação de bases de dados, a destruição de serviços, as alterações de equipas e a remoção de configurações devem continuar a exigir aprovação.

Como é que o Codex encontra ou cria o serviço correto?

Faça da descoberta a primeira operação. Não peça ao Codex para transformar “Payments API” num slug presumido:

dockup services --json

Cada resultado inclui um target exato no formato project/service. O Codex deve copiar esse valor para os comandos seguintes e devolvê-lo no resumo.

Quando não existe nenhum serviço, crie um a partir do Git:

dockup create payments-api \
  --repo https://github.com/acme/payments-api \
  --project production \
  --branch main \
  --deploy \
  --wait \
  --link \
  --json

O comando cria o serviço, faz o deploy, bloqueia até o deploy ser resolvido e grava um link .dockup no diretório de trabalho. É utilizado um Dockerfile quando este existe; caso contrário, o Nixpacks faz a deteção automática do build.

Quando o Codex perde o estado da sessão ou um workflow é executado novamente após uma interrupção de rede, deve redescobrir os serviços e verificar o target exato antes de alterar qualquer coisa. Se o target já existir, deve continuar a partir do seu estado e histórico de deploys, em vez de emitir outro pedido de criação.

A sequência completa, orientada pelo repositório, está disponível em Do repositório Git à produção.

Como deve o Codex preparar a configuração antes do deploy?

Peça ao Codex para inspecionar os metadados atuais do serviço antes de os alterar:

dockup info production/payments-api --json
dockup env list -s production/payments-api --json

A resposta do ambiente inclui as chaves e os indicadores isSecret, enquanto os valores dos secrets permanecem ocultos. O Codex pode adicionar variáveis comuns e secrets separadamente:

dockup env set NODE_ENV=production \
  -s production/payments-api \
  --json

dockup env set STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY" \
  --secret \
  -s production/payments-api \
  --json

Nunca coloque um secret de produção em dockup.yaml; o manifest é adequado para configurações simples e sujeitas a revisão, não para credenciais. As variáveis de secret existentes não são substituídas nem removidas pelo workflow de configuração como código.

Configure a porta de escuta e o readiness check do serviço quando forem conhecidos:

dockup set production/payments-api --port 3000 --json
dockup health production/payments-api \
  --path /health \
  --interval 5 \
  --retries 5 \
  --json

Um readiness gate torna significativa a verificação em produção. A plataforma executa um deploy blue-green e encaminha o tráfego apenas depois de a nova versão satisfazer o gate.

Como é que a verificação em produção confirma o estado terminal?

Para um serviço existente, use um único comando:

dockup deploy production/payments-api \
  --wait \
  --timeout 900 \
  --json

O timeout explícito corresponde aos 900 segundos predefinidos e torna visível a intenção do workflow. O exit 0 significa que o deploy foi bem-sucedido. Um resultado diferente de zero com deploy_failed significa que o build ou o deploy falhou. deploy_timeout significa que a operação ainda não tinha chegado a um estado terminal quando terminou o período de espera.

A lógica correta de branching do Codex baseia-se no estado do processo:

Resultado	Ação do Codex
Exit 0, status:"success"	Continuar para as verificações de health, uptime e segurança
deploy_failed	Ler os build logs e identificar o primeiro erro acionável
deploy_timeout	Comunicar a incerteza; inspecionar o estado ou repetir com um timeout justificado
not_logged_in	Parar e solicitar um token válido
needs_confirm	Parar e solicitar aprovação humana

Depois de um deploy do Codex bem-sucedido, recolha evidências observáveis:

dockup status production/payments-api --json
dockup uptime production/payments-api --hours 24 --json
dockup security production/payments-api --json

As verificações de uptime são executadas a cada minuto e incluem estatísticas de tempo de resposta, como p95. Os resultados de segurança incluem CVEs da imagem e verificações de configuração. Estes sinais não comprovam a correção do negócio, por isso o Codex também deve executar os smoke tests do próprio repositório, quando disponíveis.

Como deve o Codex diagnosticar e recuperar de um release falhado?

Erros de build e erros de runtime exigem logs diferentes. Use o output do build mais recente quando o deploy nunca tiver chegado a um container executável:

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

Use os logs de runtime quando a imagem tiver sido criada, mas a aplicação falhar, ficar ligada à porta errada ou falhar depois do arranque:

dockup logs production/payments-api --json

O modo follow é útil durante um build longo:

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

No modo JSON, o output do follow é NDJSON, permitindo ao Codex processar cada batch à medida que chega. O stream termina num estado terminal do deploy e preserva o exit code real da falha.

A recuperação começa pelo histórico, não por um target de rollback presumido:

dockup deployments production/payments-api -n 20 --json
dockup rollback <deploymentId> production/payments-api --json

O Codex deve identificar um deploy conhecido como bem-sucedido, indicar o ID selecionado e preservar as evidências da falha antes de o executar novamente. Nunca deve escolher “o segundo item” sem verificar o estado e os timestamps.

Um relatório final útil tem sete campos: target, branch ou commit, ID do deploy, exit code, estado terminal, URL de produção e ações seguintes. Este formato torna cada deploy do Codex analisável por uma pessoa ou por um passo de automação posterior.

Um script de verificação compacto

Este padrão de shell mantém o deploy e o diagnóstico num único fluxo de controlo transparente:

if dockup deploy production/payments-api --wait --json > deploy-result.json; then
  dockup status production/payments-api --json
  dockup uptime production/payments-api --hours 24 --json
else
  dockup logs production/payments-api --build --json
  exit 1
fi

O script não procura uma frase de sucesso com grep. Confia no exit code da CLI, mantém o JSON do deploy e faz falhar o job chamador quando a produção não chega a um estado de sucesso.

Torne as novas tentativas observáveis, em vez de invisíveis

As sessões do agente podem ser interrompidas depois de uma operação começar, mas antes de o resultado chegar à transcrição. A execução seguinte do Codex não deve repetir cegamente todas as mutações. Deve redescobrir o serviço, inspecionar o deploy mais recente e determinar se a operação anterior chegou a um estado terminal.

Um runbook de deploy do Codex deve classificar os comandos como seguros para repetir, seguros apenas depois de uma inspeção ou dependentes de aprovação. As leituras são seguras para repetir. A criação de serviços exige uma descoberta prévia. Um novo deploy é um novo evento de produção e deve ser registado como tal. A remoção e outras operações destrutivas continuam a ser decisões humanas.

Separe a verificação da plataforma da verificação da aplicação

O Dockup pode comprovar que um build terminou, que o container ficou pronto e que probes ao nível do minuto observam o serviço público. Ainda assim, o Codex deve executar verificações específicas da aplicação: um endpoint público de health, um pedido de teste autenticado ou um smoke test fornecido pelo repositório que não altere dados de clientes.

O resultado final deve indicar ambas as camadas. “O deploy da plataforma foi bem-sucedido” e “o smoke test da aplicação passou” são afirmações diferentes. Quando apenas a primeira estiver disponível, o Codex deve dizê-lo, em vez de comprimir a incerteza num visto verde.

Confirme a superfície de comandos instalada antes da automação

Uma tarefa reutilizável do Codex deve começar por verificar dockup skill status --json e abrir a referência atual da CLI quando depender de uma opção menos familiar. Isto impede que uma sessão siga um exemplo escrito para outra release.

A verificação é especialmente útil em runners efémeros, onde uma nova instalação global de npm pode diferir da existente no laptop de um developer. O Codex pode comunicar o estado da skill antes de executar a primeira operação de escrita em produção, tornando o registo do deploy reproduzível.

Handoff final

Guarde as evidências.

Mantenha o target visível

Devolva o target exato do serviço no relatório final.

Preserve a decisão sobre a origem

Registe se o Dockup utilizou o Dockerfile do repositório ou o Nixpacks. Este facto ajuda a sessão seguinte do Codex a escolher o log de build correto e evita que uma alteração na estrutura da origem seja confundida com um incidente da plataforma.

Registe também se o deploy automático após um push está ativado. Caso contrário, um release manual do agente e um release acionado por um push podem sobrepor-se e criar dois eventos de produção a partir da mesma investigação.

Coloque o workflow em produção

Execute o primeiro deploy do Codex contra um serviço descartável ou de baixo risco e, em seguida, promova o mesmo contrato de comandos verificado para produção.

npm install -g dockup-cli
dockup skill install

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

FAQ

O Codex pode fazer o deploy de um novo repositório Git com um único comando?

Sim. dockup create pode criar o serviço, fazer o deploy, aguardar o resultado terminal e criar um link para o diretório atual quando utilizado com --deploy, --wait e --link.

Como deve o Codex autenticar-se no Dockup?

Use DOCKUP_TOKEN no ambiente do processo e verifique-o com dockup whoami --json. Isto evita o login interativo através do browser em sandboxes e CI.

O que comprova que um deploy do Codex foi bem-sucedido?

O comando de deploy deve terminar com exit 0 depois de ser executado com --wait, e o respetivo JSON deve indicar um estado terminal bem-sucedido. Em seguida, execute verificações de status, uptime e smoke tests da aplicação.

O Codex pode ler secrets de produção no Dockup?

Não. Os valores dos secrets aparecem ocultos no output. O Codex pode definir ou substituir um secret, mas não recebe o valor armazenado ao listar a configuração.

O que deve o Codex fazer com needs_confirm?

Deve parar e solicitar aprovação humana explícita. O erro indica que foi tentado executar um comando destrutivo sem a confirmação --yes necessária.