mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-16 20:13:04 +00:00
- 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
11 KiB
11 KiB
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.ymlroda 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 demaincom 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.ymlcontinua 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/eAGENTS.mdestão no build context (o Dockerfile fazCOPY . .) → 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-onhost, ~segundos): checkout comfetch-depth: 0→ssh homeserverlê o SHA deployado do~/stack/docker-compose.yml(image: teqo-1313:<sha>) →git diff --name-only <sha> HEAD→scripts/ci-classify-production.mjsclassifica pelos padrões do.dockerignore(semântica moby, matcher puro em Node stdlib, sem pnpm). Jobdeployganha guard de idempotência no script remoto ("compose já referencia o SHA → exit 0"). Recomendada. - B) Gate comparando
HEADvs ú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):
- Gate
checkemruns-on: host(não container): precisa dessh homeserver(a chave vive no host da workstation — mesmo padrão do jobdeploy, OPS53). Segurança: job só emci.yml(main + dispatch), nunca emci-pr.yml— mesma premissa já validada no OPS53. - Fail-open no gate: o gate lê a revision do container rodando no
homeserver (
docker inspect→ labelorg.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) → imprimeproduction=truee 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'. - Deploy condicionado duplo:
needs: [checks, gate]+if: needs.checks.result == 'success' && needs.gate.outputs.production == 'true'— sem isso, umifsó no output rodaria deploy com suite vermelha (semântica do Actions:ifverdadeiro venceneedsfalho). - Rollup
checksintocado:if: always()+all(success or skipped)já aceita jobs skipped → run verde com chips skipped quando nada a fazer. - Classificador: matcher de
.dockerignore(moby semantics: padrão sem/casa basename em qualquer profundidade;!negação;/ancorado à raiz;/dir/só diretório;**) + CLIscripts/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. - 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). - Remoção do
on: push: branch protection do main exige apenasCI (PR) / checks*(cascade doci-pr.yml) — merges não dependem doci.ymlpós-merge (verificado emscripts/configure-branch-protection.mjselib/branch-protection.mjs).agent-pr-ready-automergeeissue-done-on-main-mergesão eventos de PR — intocados. fetch-depth: 0no jobgate— o diff<deployado>..HEADprecisa do histórico; custo de 1 clone full a cada 30 min é desprezível vs a suite. Overlap de janelas (suite > 30 min, semconcurrencyno Forgejo): limitado e auto-dedup via revision deployada (a segunda janela vê deploy == HEAD → skip); flock serializa deploy. Documentado como limite conhecido.- Hardening pós-review: job
gatecomactions/setup-node@v5(node 24 explícito no host), restrito agithub.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;productionextraído vianode -pe).
Componentes / mudanças
.forgejo/workflows/ci.yml:on:viraschedule */30+workflow_dispatch(removepush); jobgatenovo (host, main-only, outputproduction);static/int/build/e2eganhamneeds: [gate]+iffail-open;deployganhaneeds: [checks, gate]+ifduplo. 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ãogit diff --name-only <sha> HEAD→ classifica; JSON no stdout (--valuepara 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
- Classificador core —
lib/dockerignore.mjs+ci-classify-production.mjs- specs unit (matcher contra o
.dockerignorereal; classify pure; CLI via--files-from; fail-open: sem SHA deployado / dispatch / erro → true).
- specs unit (matcher contra o
- Workflow + pool —
ci.yml(schedule + gate + ifs), deleteagent-pool.yml,HIGH_RISK_EXACT, pins dociSkipInvariants(janela 30, sempush, gate existe, ifs fail-open) edeployScript(guard "already deployed"). - 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 deci.ymleagent-pool.yml),docs/changelog/2026-08-18-ops65.md+pnpm changelog:build, statusentregueno plano de intenção. - Gates —
pnpm gate:fast,pnpm format:check,pnpm knip,pnpm check:cycles,pnpm buildlocal. Sem mudança emsrc/→ 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 homeserverfalha 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.