# 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
```mermaid
flowchart LR
M[merge em main] --> S[schedule */30 ou workflow_dispatch]
S --> C[check: runs-on host
lê SHA deployado do compose no homeserver
git diff --name-only HEAD]
C --> G{produção mudou?
dockerignore do build context}
G -->|não| SK[suite + deploy skipped
run verde]
G -->|sim| SU[suite full]
SU --> CH[checks rollup]
CH --> D[deploy: já deployado?
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:`) → `git diff --name-only 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 `/`--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 `..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 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
- [x] Aceite de produto da intenção ainda coberto (janela 30 min; run verde
com skipped; pool morto; dispatch imediato; deploy gated)
- [x] Invariantes AGENTS/engineering-standards (sem segredos novos; guards de
dev/test intocados; nada de Neon; host jobs só em ci.yml)
- [x] 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.