7.5 KiB
OPS107 — Aprovar e deployar em produção a versão escolhida, sem fila de pendentes
Status: rascunho Atualizado em: 2026-09-14 Issue: #1002 Priority: P2 Impeccable: A — N/A sem UI Rascunho UI: N/A — sem UI Appetite: ~0,5–1 dia eng; um outcome verificável Responsável: —
Intenção
"A ação deploy atual não me permite aceitar o production deploy do ultimo run, eu preciso ir aceitando e deployando em prod todos os que estão pending na ordem. Não quero isso. Quero poder aceitar e fazer o deploy da versão que eu quiser. O que geralmente será o ultimo deploy bem sucedido em staging. Não quero ter que voltar deployando um a um em prod pra chegar no mais recente."
Desde a OPS104 o deploy começa sozinho no push para main: preflight → verify completo → staging automático → produção aguardando o reviewer humano. O que produto não previu é o efeito colateral da aprovação em espera: um job aguardando aprovação segura o grupo deploy-homeserver (a avaliação de concurrency do GitHub acontece antes do approval), então os runs seguintes ficam pending — inclusive o staging deles. Evidência ao vivo (2026-09-14): o run 34818635060 ficou com deploy-production aguardando de ~08:22 a ~10:12; nesse intervalo, os runs 34822356060 e 34824353858 tiveram o deploy-staging preso desde 08:38 e 09:06. Para chegar no mais recente, o operador é forçado a aprovar — e portanto publicar — os antigos em ordem. O runbook já registrou isso como falha conhecida (docs/ops/teqo-1313-deploy.md l.256) com o gatilho de revisita explícito: "aprovações demorando sistematicamente". Este item é esse gatilho, disparado.
Persona e fluxo
- Persona / contexto: o operador do deploy (hoje o
fsolla) aprovando produção pelo GitHub Actions, de mesa, com vários runs empilhados no mesmo dia. - Job principal: escolher e publicar em produção o run que ele quiser — tipicamente o último com staging verde — sem ser obrigado a aprovar/deployar os anteriores.
- Fluxo desejado: merges chegam → cada run faz verify e staging (sem esperar aprovação alheia) → o operador vê os runs aprováveis e escolhe um → aprova esse e o SHA dele publica; os antigos continuam parados onde estão, sem publicar nada.
- Anti-goals de produto: nunca auto-aprovar ou auto-publicar produção; nunca atalhar o
verifycompleto; nunca introduzir um segundo pipeline/workflow gêmeo para produção; nunca cancelar runs automaticamente sem decisão de produto.
Objetivo e aceite
- Com N runs empilhados, o operador aprova e publica qualquer um deles — tipicamente o último com staging verde — sem tocar nos anteriores.
- Um run aguardando aprovação não bloqueia o staging nem a aprovação de runs novos (esta é a mudança central).
- Aprovar o run escolhido publica o SHA dele; runs antigos não aprovados não deployam nada.
- A publicação segue exclusivamente humana, com
verifycompleto verde; nada é auto-aprovado, auto-cancelado ou atalhado.
Dados (intenção)
- Vou apresentar dados? Não — N/A: sem superfície de dados para o usuário final; a evidência é o estado dos runs no Actions (jobs
pending/waiting, ordem de liberação do grupo). - Decisões desbloqueadas: o operador decide qual run virar produção, na ordem que quiser; ninguém precisa "limpar a fila" para chegar ao mais recente.
- Forma: N/A — nada a apresentar.
Dados da decisão (literais)
- Nunca auto-approve; nunca atalhar o
verifycompleto; aprovação de produção é sempre humana. - Um run aguardando aprovação não pode bloquear o staging nem a aprovação de runs novos.
- Aprovar o run escolhido publica o SHA dele; runs antigos não escolhidos não deployam nada.
- Fora de escopo: re-deploy de SHA arbitrário (rollback continua manual no homeserver, seção Rollback do runbook) e auto-cancelamento destrutivo (decidido no gate: não).
- Multi-aprovação: o último deploy executado vence; o runbook registra "aprove só o escolhido; rejeite os demais" (decidido no gate).
- ID reservado OPS107; kind chore; sem UI (Impeccable A).
Direção no codebase (hipótese)
- Áreas prováveis:
.github/workflows/deploy.yml(jobsdeploy-stagingedeploy-production, environments e o grupodeploy-homeserver; staging l.213–221, produção l.267–270); pins emtests/unit/ciSkipInvariants.unit.spec.ts(l.156–178) etests/unit/deployTrigger.unit.spec.ts. - Precedente a olhar: OPS103/OPS104 (
docs/plans/ops104-disparo-automatico-do-deploy.mdl.25, 43, 60, 77–79, 90) e o jobrequeuedodeploy.yml(l.229–249) — que já fica fora do grupo exatamente para umwaitingnão bloqueá-lo; este item generaliza a lição. - Risco de acoplamento:
scripts/deploy-homeserver.shjá temflockúnico e guard "already deployed" — a serialização real no host não pode ser afrouxada;verifyeci-pr.ymlnão se tocam; nenhum workflow gêmeo.
Dependências
- Nenhuma.
Fora de escopo
- Auto-approve/auto-publicação (destino: nunca) e atalho do
verifycompleto (destino: nunca). - Auto-cancelamento destrutivo de runs antigos (só com decisão de produto pela opção B).
- Re-deploy de SHA arbitrário/rollback por versão: rollback continua manual no homeserver (seção Rollback do runbook).
- Mexer no
verify, noci-pr.yml, nos guards de banco ou na proteção de branch.
Rabbit holes de produto
- "Já que destrava a fila, deixa automático." Auto-approve remove o único gate que valida o SHA antes de produção. Corte neste item: produção só publica com reviewer humano; approve automático não existe.
- "Cancela tudo que é antigo." Automação destrutiva sem pedido apaga a escolha do operador e complica auditoria. Corte neste item: antigos ficam pendentes e podem ser rejeitados na UI sem deployar (opção B só se produto pedir).
- "Faz um workflow só de produção." Pipeline gêmeo cria drift e um lugar a mais onde o fluxo escapa dos gates. Corte neste item: o dono continua sendo o
deploy.yml.
Questões em aberto (produto)
- Como liberar a escolha sem auto-aprovar nada? Decidido no gate (2026-09-14): A — desacoplar a aprovação da lane de deploy; runs com staging verde ficam todos aprováveis independentemente; antigos seguem pendentes (rejeitáveis na UI, sem publicar); sem supersessão/cancelamento automático (B) e sem produção por dispatch manual (C).
- Aprovar mais de um run (acidental ou de propósito): quem vence? Decidido no gate (2026-09-14): A — manter a serialização por ordem de aprovação/execução (o último deploy executado vence); o runbook registra "aprove só o escolhido; rejeite os demais"; nenhum mecanismo novo de trava (B).
Referências
- GitHub Issue #— (a registrar via
pnpm agent:register) .github/workflows/deploy.yml— environments e concurrency (staging l.202–227; requeue l.229–249; produção l.251–276)docs/ops/teqo-1313-deploy.md— "Gatilho e fluxo" (l.12–87) e "Falhas conhecidas" (l.256, o gatilho de revisita)tests/unit/ciSkipInvariants.unit.spec.ts(l.156–178) etests/unit/deployTrigger.unit.spec.ts— pins do fluxo atualdocs/plans/ops104-disparo-automatico-do-deploy.md— decisões revisitadas (runs antigos ficam pendentes ou são cancelados à mão)scripts/deploy-homeserver.sh—flockúnico e guard "already deployed" (não afrouxar)docs/AGENT-OPS.md,AGENTS-infra.md,AGENTS.md,README.md— citações do fluxo de deploy a realinhar; entrada emdocs/changelog/