teqo-backup/docs/plans/ops65-ci-main-janela-30min-e-matar-pool-impl.md
Francisco Solla 9504c7ccf6 ops(OPS65): CI do main em janela de 30 min (gate .dockerignore fail-open) + matar agent-pool
- ci.yml: on push removido → schedule */30 + workflow_dispatch (fundido com a
  estrutura de job único sequencial do OPS62 X1)
- job gate (host, main-only, sem pnpm): revision do container rodando no
  homeserver (label org.opencontainers.image.revision — o compose pode mentir
  após rollback falho) + diff + classificador .dockerignore
- fail-open: revision desconhecida → suite roda (verde); incapaz de classificar
  → run vermelho (nunca blackout silencioso); deploy duplo-gated
  (needs: [checks, gate] + if explícito)
- deploy-homeserver.sh: guard 'already deployed' idempotente (mesma revision)
- agent-pool.yml removido; pool dormente (144 pnpm install/dia no tick */10)
- specs: dockerignoreMatch, ciClassifyProduction (incl. git-diff com repo
  scratch e exit codes), pins ciSkipInvariants/deployScript; HIGH_RISK_EXACT
- docs: runbook (janela/gate/verificação ao vivo/falhas), AGENTS.md,
  AGENT-OPS.md (tabela X1 fundida), skills pool dormente, changelog OPS65
- impl plan aprovado; intenção marcada entregue
2026-08-18 21:08:12 -03:00

11 KiB
Raw Permalink Blame History

Impl: CI do main em janela de 30 min + matar o agent-pool

Status: aprovado Atualizado em: 2026-08-18 Issue: #64 Intenção: docs/plans/ops65-ci-main-janela-30min-e-matar-pool.md Appetite restante: herdado (~0,5–1 dia eng; um outcome verificável)

Leitura da intenção

  • Outcome: a workstation deixa de pagar a CI do main a cada merge e o tick do agent-pool. ci.yml roda por janela fixa de 30 min (schedule */30 + workflow_dispatch), com um gate barato (~segundos, sem pnpm) que classifica "mudança de produção" comparando o HEAD de main com o SHA deployado no homeserver; sem mudança → suite + deploy skipped, run verde. Deploy manual (dispatch) continua imediato. agent-pool.yml é removido.
  • O que NÃO negociar: não remover a verificação pós-merge do main (o ci.yml continua o verificador); deploy continua gated pelo verificador verde; sem segundo mecanismo de deploy fora do pipeline; nada de requeue estilo cooldown (janela fixa é o corte).
  • O que reavaliar: a hipótese de "classificar por .dockerignore" é confirmada — e é a única abordagem que falha fechado (qualquer dúvida → suite roda; ver anti-goal "não remover a verificação do main"). O exemplo do aceite ("só docs/scripts/skills/AGENTS → skip") não vale literalmente sob .dockerignore: scripts/, tests/, .forgejo/ e AGENTS.md estão no build context (o Dockerfile faz COPY . .) → contam como produção. Decisão resolvida pela direção explícita do plano (.dockerignore é a fonte da verdade) + anti-goal: a classificação é conservadora (mais runs, nunca menos). Só docs/, .agents/, .env*, artefatos etc. viram skip.

Abordagem recomendada

flowchart LR
  M[merge em main] --> S[schedule */30 ou workflow_dispatch]
  S --> C[check: runs-on host<br/>lê SHA deployado do compose no homeserver<br/>git diff --name-only <deployado> HEAD]
  C --> G{produção mudou?<br/>dockerignore do build context}
  G -->|não| SK[suite + deploy skipped<br/>run verde]
  G -->|sim| SU[suite full]
  SU --> CH[checks rollup]
  CH --> D[deploy: já deployado?<br/>guard idempotente]
  D -->|compose já no SHA| DONE[skip verde]
  D -->|SHA novo| DEP[build + migrate + rollout homeserver]

Opções consideradas:

  • A) Gate check (runs-on host, ~segundos): checkout com fetch-depth: 0 → ssh homeserver lê o SHA deployado do ~/stack/docker-compose.yml (image: teqo-1313:<sha>) → git diff --name-only <sha> HEAD → scripts/ci-classify-production.mjs classifica pelos padrões do .dockerignore (semântica moby, matcher puro em Node stdlib, sem pnpm). Job deploy ganha guard de idempotência no script remoto ("compose já referencia o SHA → exit 0"). Recomendada.
  • B) Gate comparando HEAD vs último SHA conhecido do run anterior (estado em arquivo na workstation / Forgejo API). Rejeitada — o estado real da produção vive no homeserver; derivar de artefatos de CI mente quando um run falha no meio (compose restaurado no rollback = a verdade).
  • C) Whitelist manual de "caminhos de produção" (src/, public/, Dockerfile…). Rejeitada — drift e falha aberto: um caminho esquecido → suite pulada indevidamente → main não verificado, exatamente o anti-goal. .dockerignore é auto-mantido e é o que define o artefato.

Decisões de engenharia (com rejeitadas):

  1. Gate check em runs-on: host (não container): precisa de ssh homeserver (a chave vive no host da workstation — mesmo padrão do job deploy, OPS53). Segurança: job só em ci.yml (main + dispatch), nunca em ci-pr.yml — mesma premissa já validada no OPS53.
  2. Fail-open no gate: o gate lê a revision do container rodando no homeserver (docker inspect → label org.opencontainers.image.revision; o compose pode mentir após rollback falho, pois é trocado antes do rollout). Revision desconhecida (label ausente/container sem label) → production = true (suite roda, run verde). Gate incapaz de classificar (erro de git/.dockerignore/sem input) → imprime production=true e sai com exit não-zero → o run fica vermelho (nunca blackout silencioso). Deploy nunca roda no escuro: condição dos jobs da suite é needs.gate.result != 'success' || needs.gate.outputs.production == 'true'.
  3. Deploy condicionado duplo: needs: [checks, gate] + if: needs.checks.result == 'success' && needs.gate.outputs.production == 'true' — sem isso, um if só no output rodaria deploy com suite vermelha (semântica do Actions: if verdadeiro vence needs falho).
  4. Rollup checks intocado: if: always() + all(success or skipped) já aceita jobs skipped → run verde com chips skipped quando nada a fazer.
  5. Classificador: matcher de .dockerignore (moby semantics: padrão sem / casa basename em qualquer profundidade; ! negação; / ancorado à raiz; /dir/ só diretório; **) + CLI scripts/ci-classify-production.mjs (--deployed <sha>/--files-from, --value; dispatch → produção forçada; exit 0 = classificou, exit 1 = não classificou). Sem pnpm, sem deps.
  6. Guard "already deployed" no deploy-homeserver.sh: após o HEAD guard + flock, antes de sourcear secrets: se o container rodando já tem a revision do SHA → exit 0 ("nothing to do"). Mata o rebuild de ~15 min em dispatch duplicado. Container sem label/fora = "não deployado" (procede — direção segura). Sem flag FORCE (YAGNI; força = fluxo manual do runbook).
  7. Remoção do on: push: branch protection do main exige apenas CI (PR) / checks* (cascade do ci-pr.yml) — merges não dependem do ci.yml pós-merge (verificado em scripts/configure-branch-protection.mjs e lib/branch-protection.mjs). agent-pr-ready-automerge e issue-done-on-main-merge são eventos de PR — intocados.
  8. fetch-depth: 0 no job gate — o diff <deployado>..HEAD precisa do histórico; custo de 1 clone full a cada 30 min é desprezível vs a suite. Overlap de janelas (suite > 30 min, sem concurrency no Forgejo): limitado e auto-dedup via revision deployada (a segunda janela vê deploy == HEAD → skip); flock serializa deploy. Documentado como limite conhecido.
  9. Hardening pós-review: job gate com actions/setup-node@v5 (node 24 explícito no host), restrito a github.ref == 'refs/heads/main' (dispatch em branch não roda código do branch no host — a suite roda fail-open em containers com secrets de teste), e invocação única do classificador (JSON capturado uma vez; production extraído via node -pe).

Componentes / mudanças

  • .forgejo/workflows/ci.yml: on: vira schedule */30 + workflow_dispatch (remove push); job gate novo (host, main-only, output production); static/int/build/e2e ganham needs: [gate] + if fail-open; deploy ganha needs: [checks, gate] + if duplo. Cabeçalho atualizado.
  • .forgejo/workflows/agent-pool.yml: removido (scripts/skills/docs do pool ficam dormentes — aceite).
  • scripts/lib/dockerignore.mjs (novo): parseDockerignore / isIgnoredPath — matcher puro de .dockerignore (moby semantics), stdlib.
  • scripts/ci-classify-production.mjs (novo): CLI — dispatch → true; SHA deployado ausente → true; senão git diff --name-only <sha> HEAD → classifica; JSON no stdout (--value para o workflow); erro interno → true
    • stderr (fail-open), exit 0.
  • scripts/deploy-homeserver.sh: guard "already deployed" (compose já referencia o SHA → skip verde) após o flock, antes dos secrets.
  • scripts/lib/test-affected-core.mjs: HIGH_RISK_EXACT += scripts/ci-classify-production.mjs, scripts/lib/dockerignore.mjs (mudar o classificador força suite full no PR — padrão existente).
  • Migration: sem migration.
  • Access / Consent: N/A.
  • UI: Impeccable A — sem UI.

Dados → forma

N/A — política de infra/CI.

Fases verificáveis

  1. Classificador core — lib/dockerignore.mjs + ci-classify-production.mjs
    • specs unit (matcher contra o .dockerignore real; classify pure; CLI via --files-from; fail-open: sem SHA deployado / dispatch / erro → true).
  2. Workflow + pool — ci.yml (schedule + gate + ifs), delete agent-pool.yml, HIGH_RISK_EXACT, pins do ciSkipInvariants (janela 30, sem push, gate existe, ifs fail-open) e deployScript (guard "already deployed").
  3. Docs + changelog — runbook docs/ops/teqo-1313-deploy.md (janela, gate, "already deployed", falhas conhecidas: ssh do gate falha → fail-open; overlap), AGENTS.md (parágrafo CI/deploy), docs/AGENT-OPS.md (linhas de ci.yml e agent-pool.yml), docs/changelog/2026-08-18-ops65.md + pnpm changelog:build, status entregue no plano de intenção.
  4. Gates — pnpm gate:fast, pnpm format:check, pnpm knip, pnpm check:cycles, pnpm build local. Sem mudança em src/ → e2e do PR skip por affected.

Rabbit holes / Não escopo (engenharia)

  • Reimplementar cooldown GitHub (defer/requeue) — corte do plano; janela fixa.
  • Classificação fina por tipo de arquivo (whitelist) — corte do plano; .dockerignore é a fonte da verdade.
  • Flag FORCE no deploy / UI de deploy — runbook basta.
  • Limpar scripts/skills/docs do pool — dormentes por aceite.
  • Mover a CI para VPS/homeserver — fora de escopo do plano.

Riscos e mitigação

  • ssh homeserver falha no gate → fail-open (suite roda); deploy fica para a próxima janela (≤30 min, auto-cura). Runbook documenta.
  • Overlap de janelas (suite > 30 min) → segunda suite no mesmo SHA (raro, limitado); flock serializa; SHA deployado dedupa a janela seguinte.
  • Dispatch do mesmo SHA → suite roda (intenção explícita), deploy skip verde "already deployed"; força via fluxo manual do runbook.
  • Remoção do push → "merge != deploy imediato" → aceite explícito da intenção (≤30 min); dispatch cobre urgência; falha de deploy continua vermelha e o site fica no container antigo.
  • Deploy antigo sobrescrevendo push novo → HEAD guard + flock intactos.

Aceite de engenharia

  • Aceite de produto da intenção ainda coberto (janela 30 min; run verde com skipped; pool morto; dispatch imediato; deploy gated)
  • Invariantes AGENTS/engineering-standards (sem segredos novos; guards de dev/test intocados; nada de Neon; host jobs só em ci.yml)
  • Testes previstos (unit: matcher + classificador + pins de workflow e script de deploy)

Self-score decision-quality: 1) decisões caras com rejeitadas ✓ 2) cabe no appetite ✓ 3) rabbit holes nomeados ✓ 4) reusa padrões existentes (OPS53 host job + ssh, flock, HEAD guard, ciSkipInvariants/deployScript pins, HIGH_RISK) ✓ 5) aceite da intenção preservado, com uma divergência explícita de exemplo do aceite (scripts/tests/AGENTS contam como produção por .dockerignore — conservador, alinhado ao anti-goal) ✓ — 5/5.