Portão de Pré-Envio

Visão Geral

A maioria dos deploys ruins não falha de forma explícita. O pipeline fica verde, o CLI exibe "deploy realizado", e a versão antiga ou quebrada ainda é a que os usuários acessam. Esta habilidade é o portão que você executa logo antes de um deploy em produção e logo depois, para que um agente pare de confiar na saída do deploy e comece a confirmar o que está realmente ativo. Ela existe porque "o comando de deploy saiu com código 0" e "a nova versão está servindo tráfego" são dois fatos diferentes, e os agentes rotineiramente os confundem.

Quando Usar Esta Habilidade

• Use antes de executar qualquer comando que envie para um ambiente de produção ou staging.
• Use quando um agente estiver prestes a relatar "enviado", "deploy realizado" ou "ativo".
• Use quando um deploy relatou sucesso, mas os usuários ainda veem o comportamento antigo.
• Use quando um lançamento envolve migrações de banco de dados, flags de recursos ou um rollout gradual.

Como Funciona

O portão tem três fases. Não pule para a fase 3.

Fase 1: Pré-voo (antes do deploy ser executado)

Percorra o catálogo de falhas silenciosas. Estes são os modos que permitem que um deploy "tenha sucesso" enquanto a produção permanece quebrada. Para cada um, confirme ou sinalize. Não presuma.

• Migrações: As migrações de esquema fazem parte deste lançamento e serão executadas no alvo antes que o novo código sirva tráfego? Um deploy que envia código esperando uma coluna que ainda não existe falha silenciosamente para os usuários, não para o pipeline.
• Flags de recursos: A flag que controla esta alteração está realmente habilitada no ambiente alvo, não apenas no ambiente de desenvolvimento? Código enviado por trás de uma flag desativada parece um deploy "no-op" (sem operação).
• Cache de build / assets desatualizados: Um build em cache ou camada de CDN poderia servir o bundle anterior após o deploy? Confirme se o hash do artefato ou a impressão digital do asset mudou.
• Ponteiro de lançamento: O deploy atualiza o link simbólico, a revisão ativa ou o ponteiro de tráfego, ou apenas carrega o novo build? Carregar não é lançar.
• Rollout gradual / canário: Se o tráfego for gradual, ele está travado em 0% ou esperando uma promoção manual? Um canário que nunca é promovido não é um deploy.
• Ambiente e segredos: As variáveis de ambiente e os segredos que o novo código precisa estão presentes no alvo, não apenas localmente? Configuração ausente aparece como erros em tempo de execução, não erros de deploy.

Fase 2: Executar o deploy

O humano ou a ferramenta de deploy executa o comando real. Esta habilidade não executa o deploy de produção em si. Ela o controla.

Fase 3: Verificar o status ativo (antes de dizer "enviado")

Confirme o sistema em execução, não o log do deploy.

• Busque a versão ativa ou o identificador de revisão do serviço em execução e compare-o com o que você pretendia enviar.
• Acesse um endpoint de saúde ou status e confirme que ele retorna a versão esperada, não apenas HTTP 200.
• Monitore os logs de produção para os primeiros erros após a transição.
• Somente após a revisão ativa corresponder à revisão pretendida, você poderá relatar "enviado". Se não corresponder, relate a incompatibilidade, não o sucesso.

Exemplos

Exemplo 1: Verificando a revisão ativa em vez de confiar no log do deploy

# You intended to ship this commit
INTENDED="$(git rev-parse --short HEAD)"

# Ask the running service what it is actually serving
LIVE="$(curl -fsS https://your-service.example.com/health | jq -r '.revision')"

if [ "$INTENDED" = "$LIVE" ]; then
  echo "Live revision $LIVE matches intended $INTENDED: verified shipped."
else
  echo "MISMATCH: intended $INTENDED but live is $LIVE. Do not report shipped."
fi

Exemplo 2: Formato de veredicto pré-voo que um agente pode emitir

PRE-SHIP GATE, verdict: HOLD

- Migrations: 1 pending (add_users_status_col): NOT yet applied to prod. BLOCK.
- Feature flags: new_checkout flag is OFF in prod. Enabling required post-deploy.
- Build assets: new bundle hash confirmed (a1b2c3 != previous 9f8e7d). OK.
- Release pointer: deploy updates active symlink. OK.
- Rollout: canary at 10%, manual promote required. NOTE.
- Env/secrets: STRIPE_KEY present in prod. OK.

Reason for HOLD: run migration add_users_status_col before cutover, or the
new code will 500 on /orders.

Melhores Práticas

• ✅ Trate "o comando saiu com código 0" e "a nova versão está ativa" como fatos separados, e verifique o segundo.
• ✅ Emita um veredicto explícito (ENVIAR / SEGURAR) com o item falho nomeado, não um vago "parece bom".
• ✅ Compare um identificador de revisão ativa contra o pretendido após cada deploy.
• ✅ Nomeie o modo específico de falha silenciosa com o qual você está preocupado, para que um humano possa substituir com contexto.
• ❌ Não relate "enviado" apenas a partir da saída do deploy.

…