- issue-done/plan-issue-ready: env FORGEJO_API_TOKEN (GITHUB_TOKEN 403 em Issues) + fork guard (checkout de fork roda script do fork com o PAT — RCE) - forgejo-issue-transition: falha de flip vira exit 1 (job vermelho, nunca skip silencioso) - waitForChecks: exige o rollup CI (PR) / checks presente+verde (raça PR #52: snapshot com jobs não-agendados parecia verde); mergeable=false só conta como conflito após a cascata assentar; timeouts 30→45min (CLI) e 40→55min (workflow) - configure-branch-protection: contexto real CI (PR) / checks* (Forgejo casa por glob contra 'CI (PR) / checks (pull_request)'; literal 'checks' nunca casaria), idempotente GET→POST/PATCH, verificação pós-aplicação; decisão pura em scripts/lib/branch-protection.mjs - docs honestas (AGENT-OPS, agent-pr-workflow.mdc, CUTOVER-MAIN-ONLY, README) - testes: raça do rollup/rollup failure/mergeable pré-settle + branchProtection create/update/noop + glob real
12 KiB
12 KiB
Impl: OPS61 — Forgejo: contratos de merge/flip quebrados — labels não flipam (GITHUB_TOKEN 403) e branch protection de main não reportada
Status: aprovado Atualizado em: 2026-08-18 Issue: #53 Intenção: docs/plans/ops61-forgejo-contratos-merge-labels-e-branch-protection.md Appetite restante: herdado (~1 dia de ops)
Leitura da intenção
- Outcome: (S1) os dois workflows pós-merge usam PAT com
issues:write—Closes/Fixes #Nflipedone+in-prodeRelated #Npromovareadyem PRs reais; (S3) a regra de branch protection demain(required status check = rollupchecksdo ci-pr) existe no servidor ou as docs dizem a verdade ("gate no script, não no servidor"); (2b)waitForChecksespera o rollupCI (PR) / checks— snapshot com jobs não-agendados nunca parece verde. - O que NÃO negociar: o flip deve falhar ruidoso se falhar (rejeitado: engolir 403); nenhuma edição de Issues
in-progressde terceiros; nada de prod DB (ops de Forgejo, não de DB). - O que reavaliar: qual PAT usar (intenção sugere
POOL_GITHUB_TOKEN); por que a regra não está no servidor; o contexto exato que a regra exige (a intenção supunhachecks).
Achados da exploração (evidência ao vivo 2026-08-18)
- S1 root cause:
forgejo-api.mjsresolve token na ordemFORGEJO_API_TOKEN→GITHUB_TOKEN. Nos dois workflows pós-merge nenhumenv:injeta o PAT → cai noGITHUB_TOKENnativo, que 403 em labels/comments de Issues. Os jobs terminam success porque os scripts engolem o erro notry/catch. - Fork guard ausente nos dois workflows pós-merge:
on: pull_request: types: [closed]dispara também para PRs de fork e oactions/checkoutfaz checkout do head do fork → o script do fork roda com o token do Actions. O workflow irmãoagent-pr-ready-automerge.ymltem o guardhead.repo.full_name == github.repositoryexatamente por isso (RCE com o token). Injetar um PAT comissues:writenesses workflows sem o guard agrava o buraco — o guard entra junto. - S3 root cause:
GET /repos/fsolla/teqo/branch_protections→[](0 regras, confirmado). O changelog do OPS50 listapnpm configure:branch-protectioncomo passo humano pendente ("Pendente (parte 2): … passos humanos (secrets no Forgejo,pnpm configure:branch-protection, …)") — o script nunca rodou pós-port.CUTOVER-MAIN-ONLY.md,AGENT-OPS.mdeagent-pr-workflow.mdcdocumentam a regra como aplicada — docs mentem. - Contexto real do rollup: statuses observados do sha do PR #52/#48/#50:
CI (PR) / checks (pull_request)(contexto inclui o sufixo(evento)). Ochecksdoci-pr.ymltemif: always()+needsde todos os jobs → só posta depois da cascata inteira. - Como o Forgejo casa os contextos da regra: fonte (branch
forgejo):MergeRequiredContextsCommitStatuscompila cadastatus_check_contextscom glob (gobwas/glob,glob.Compile(ctx)) e casa contracommitStatus.Context; contexto exigido que não casa nenhum status →pending(bloqueia merge). Ou seja:checksliteral nunca casariaCI (PR) / checks (pull_request)— a regra, mesmo se aplicada com o valor atual do script, bloquearia todo merge silenciosamente. O globCI (PR) / checks*casa o rollup real (o sufixo(pull_request)não contém/, então casa com ou sem semântica de separador). - O servidor realmente bloqueia: o merge POST passa por
CheckPullBranchProtections→IsPullCommitStatusPass→ErrDisallowedToMerge(405 "PR is not ready to be merged"). A regra no servidor é a defesa final real (o plano da intenção suspeitava que o Forgejo 9 pudesse não expor; a expõe e bloqueia). - Timeouts:
waitForChecksdefault 30 min; o workflowready-automergetemtimeout-minutes: 40. Com o gate do rollup esperamos a cascata inteira (incl. e2e×2, int, build) — 30 min fica apertado sob carga (capacity 4, pool em paralelo). Subir CLI para 45 min e workflow para 55 min.
Abordagem recomendada
flowchart LR
A[PRs pós-merge: env FORGEJO_API_TOKEN + fork guard] --> B[flip real com PAT]
C[waitForChecks: gate do rollup CI (PR) / checks*] --> D[merge só com cascata completa]
E[configure-branch-protection: glob real + idempotente] --> F[regra no servidor = defesa final]
G[PR da entrega Closes #53] --> H[verificação ao vivo de S1 e S3]
Opções consideradas:
- S1: (A)
FORGEJO_API_TOKENnos dois workflows; (B)POOL_GITHUB_TOKEN; (C) PAT dedicado novo. - S3: (A) script corrigido (glob real) + idempotente + rodar; (B) rodar script como está (
checksliteral); (C) contexto literal exatoCI (PR) / checks (pull_request); (D) docs-only ("gate no script"). - 2b: (A) gate do rollup no
waitForChecks+mergeable === falsesó após cascata assentar + timeouts maiores; (B) lista exaustiva de contextos; (C) só regra no servidor.
Recomendação: S1-A + S3-A + 2b-A — porque:
- S1-A: o
forgejo-api.mjsjá prefereFORGEJO_API_TOKEN; é o PAT que o pool usa em produção para o mesmo tipo de escrita (claim = flip de labels, comments, issues) — escopoissues:writecomprovado; secret já existe no Forgejo (pool roda verde).POOL_GITHUB_TOKEN(B) existe para/actions/variables(o 403 que ele resolve é de variables, não de issues) e é redundante para este uso; (C) cria provisioning humano sem ganho. - S3-A: o glob
CI (PR) / checks*é o único valor que casa os statuses reais (achado 5); o script vira GET→POST/PATCH idempotente com dry-run honesto (criar/atualizar/no-op), fechando a promessa "idempotente" do próprio doc. (B) criaria regra que nunca casa → todo merge bloqueado (pior que nada). (C) funciona (casamento exato) mas é frágil ao formato do sufixo(evento);*é resiliente e igualmente preciso (o literalCI (PR) / checksantes do*não casa oCI / checksdo push). - 2b-A: o rollup é o único contexto com
if: always()sobre a cascata toda; exigir presença+success dele mata a raça (snapshot pré-docs-guardsnão tem rollup → pending).mergeable === falsepassa a lançar só depois do rollup assentar (senão a regra recém-aplicada faria o CLI lançar "conflito" prematuro durante a CI). (B) é frágil a mudanças de jobs; (C) sozinho faz o merge falhar ruidoso em vez de esperar — o gate no script é que espera. - Fail-loud do flip (racional da intenção):
forgejo-issue-transition.mjspassa a sair com exit 1 se qualquer flip falhar (o job é o propósito inteiro do workflow);agent-promote-related-on-merge.mjsmantém o soft-skip documentado (safety net multi-issue por design — falha de uma Issue não aborta irmãs; a troca de token é o fix da causa raiz).
Rejeitadas: engolir 403 no script (intenção veto); POOL_GITHUB_TOKEN (semântica de variables); checks literal (glob nunca casa — merges bloqueados para sempre); lista de contextos (frágil); confiar só no servidor (merge falha em vez de esperar); docs-only (a regra funciona e é a defesa final real).
Componentes / mudanças
.forgejo/workflows/issue-done-on-main-merge.yml:if:ganha o fork guard (head.repo.full_name == github.repository); jobenv: FORGEJO_API_TOKEN: ${{ secrets.FORGEJO_API_TOKEN }}; comentário do header explica o PAT (GITHUB_TOKEN 403 em Issues)..forgejo/workflows/plan-issue-ready-on-main-merge.yml: idem (fork guard + env + header).scripts/lib/forgejo-api.mjs(waitForChecks): novo gate — entre os statuses do sha, o contexto que começa comCI (PR) / checksdeve existir e sersuccess(failure/error → throw; ausente/pending → continua poll);mergeable === falsesó lança se o rollup já assentou (success); restante (failure/error de outros contextos, pending, draft, timeout) preservado.scripts/forgejo-pr-automerge.mjs: passatimeoutMs: 45 * 60 * 1000explícito aoautoMerge..forgejo/workflows/agent-pr-ready-automerge.yml:timeout-minutes: 40→55.scripts/forgejo-issue-transition.mjs: falhas de flip viram exit 1 (log continua por Issue, comcontinueentre irmãs — não aborta a lista inteira, mas o job vermelha).scripts/configure-branch-protection.mjs:status_check_contexts: ['CI (PR) / checks*']; fluxo idempotente GET → POST (cria) / PATCH (atualiza se drift) / no-op (igual); dry-run imprime a ação exata; após aplicar, re-lê e loga a regra.scripts/lib/branch-protection.mjs(novo, puro):planBranchProtectionRule(existing, desired)→create | update | noop(testável). Reusa o shape da API.- Docs:
docs/AGENT-OPS.md(tabela de workflows: token usado; secrets: nota queFORGEJO_API_TOKENcobre os pós-merge; estado da branch protection),.agents/rules/agent-pr-workflow.mdc(seção "Required checks": contexto literalCI (PR) / checks, regra aplicada no servidor; seção safety net: gate do rollup),docs/CUTOVER-MAIN-ONLY.md(checkbox da branch protection = aplicado em 2026-08-18),README.md(linha 5 stale: removeVERCEL_*, atualiza a linha da branch protection). - Tests:
tests/unit/forgejoApi.unit.spec.ts— novos casos dewaitForChecks: (a) statuses verdes mas sem rollup → continua poll (a raça); (b) rollup presente success → retorna; (c) rollup failure → lança; (d)mergeable === falseantes do rollup assentar → continua; (e)mergeable === falseapós rollup success → lança.tests/unit/branchProtection.unit.spec.ts(novo) — decisão create/update/noop + glob casa os contextos observados. - Migration: sem migration (não toca schema/DB).
- Access / Consent: N/A.
- UI: N/A (A).
Fases verificáveis
- Scripts + workflows + docs + testes — diff completo do PR da entrega;
pnpm gate:fastlocal (lint/format/typecheck/knip/cycles/unit). - Push + PR —
pnpm push; PRCloses #53. Enquanto a CI roda: aplicar a regra no servidor (pnpm configure:branch-protection -- --dry-run→ aplicar →GET /branch_protectionsconfirma). A auto-merge da própria PR prova o gate do rollup (2b) e a regra (S3) num único ciclo:waitForChecksespera a cascata → rollup green → merge permitido pela regra → merge. Se o glob estiver errado, o merge 405/mergeable=falsefalha ruidoso e corrigimos antes de qualquer outra PR. - Flip (S1) ao vivo — o merge dispara
issue-done-on-main-merge.ymlcom o PAT; a Issue #53 viradone+in-prodcom comentário. Se não flipar, o job agora vermelha (exit 1) — visível. - Changelog —
docs/changelog/2026-08-18-ops61.md+pnpm changelog:build.
Rabbit holes / Não escopo (engenharia)
- Não mudar o soft-skip do
agent-promote-related-on-merge.mjs(design documentado; token é o fix). - Não mexer no merge do pool (usa os mesmos caminhos — herda o fix).
- Não reaplicar/alterar
enable_push/approvals da regra (0 reviews, strict=false — contrato atual). - Não corrigir o
README.mdinteiro (drift pré-existente pós-OPS50) — só a linha do escopo. - Guard de fork como débito? Não — entra na entrega (achado 2, mesmo arquivo, mesma classe do guard do irmão).
Riscos e mitigação
- Glob da regra errado → todo merge bloqueado: mitigação — verificação empírica na própria PR da entrega (Fase 2); falha é ruidosa (405/throw) e reversível (PATCH contexts); a fonte do Forgejo confirmou o casamento por glob e o valor observado.
mergeable === falseprematuro com regra aplicada durante a CI: mitigação — lançar só após o rollup assentar; a PR da entrega exercita exatamente esse caminho.- Cascata completa estoura o timeout (esperamos e2e agora): mitigação — CLI 45 min + workflow 55 min; medir na PR da entrega e ajustar se a folga for pequena.
- PRs de fork param de flipar issues pós-merge: comportamento novo e intencional (guard) — documentado no changelog; flip manual para fork PRs se algum dia precisar.
- Secret
FORGEJO_API_TOKENnão terissues:write: mitigação — o pool já escreve issues/labels/comments com ele em produção (evidência: runs verdes); se faltar escopo, o job vermelha (exit 1) e o humano ajusta o PAT — visível, não silencioso.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (flip real, regra no servidor, rollup gate, fail ruidoso)
- Invariantes AGENTS/engineering-standards (zero-dep scripts, forks nunca rodam código com token do repo, docs honestas)
- Testes de domínio previstos (unit: waitForChecks ×5, branchProtection ×3) onde os write/merge paths mudam
- Verificação ao vivo: #53 flipe
done+in-prodcom PAT;GET /branch_protectionsmostra a regra; PR da entrega mergeia pelo novo gate