docs(integration): document the review-gate tradeoff for path-α (required_approvals vs zero-touch cuts) #112

New issue

Closed

opened 2026-06-26 14:31:47 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-26 14:31:47 +02:00

Owner

Why now

The 2026-06-26 path-α activation surfaced an architectural constraint not previously documented: Forgejo's branch-protection required_approvals > 0 blocks the manifest follow-up PR's auto-merge, even when release-bot is on push_whitelist_usernames. Empirical findings from the same session:

merge_whitelist_usernames is the wrong tool — it restricts WHO can merge when general merges are disabled; it doesn't bypass required_approvals. Empirical test: enabling it locked admin out of merging.
enable_approvals_whitelist + approvals_whitelist_username makes specific reviewers' approvals count as official, but doesn't allow the PR author to self-approve.
Forgejo blocks self-approval globally ("approve your own pull is not allowed" HTTP 422) — not a per-repo setting. Empirical test confirmed.

So in stock Forgejo, the single-bot path-α design + a Forgejo-level review-gate are architecturally incompatible: the bot can't auto-merge its own PR if approval is required, and no native setting changes this.

The tradeoff each consumer should explicitly decide

Option	`required_approvals`	Effort-to-cut	What's lost
(2) Zero-touch cuts	`0`	Workflow auto-merges manifest PR; operator clicks only Gate-1 (rolling PR)	Forgejo-level review-gate; chamber-level review-discipline still applies via convention
(3) Operator-gated cuts	`1+`	Operator clicks Gate-1 (rolling PR) AND clicks the manifest follow-up PR	Manifest PR sits open for manual merge per cut

Other paths exist but are not recommended as defaults:

(5) Two-bot pattern — release-bot opens + merges; release-reviewer (separate bot) approves. Adds a second long-lived bot token. Operator surfaced this as "too heavy machinery" 2026-06-26.
(1) Routine human approval — a designated reviewer (e.g., the Surveyor chamber on alcatraz) routinely approves manifest PRs. Substrate-honest but adds a per-cut touch on someone else's surface.

Scope of this issue

Add a new section to docs/integration.md (probably under "Branch protection compatibility" alongside the existing α/β/γ token-path documentation):

`## Branch protection: review-gate tradeoff` (proposed)

Context: explain why path-α's auto-merge interacts with Forgejo's required_approvals setting
Empirical findings: cite the §8 Axis A worked instances from 2026-06-26 (merge_whitelist semantic, self-approval blocked) so future readers don't re-investigate
The (2) vs (3) tradeoff table: as above
Recommended default: (2) for new consumers — the chamber-level review-discipline that has empirically load-borne the v0.4.0→v0.6.2 arc-convergence is sufficient; the Forgejo-level gate only adds an interaction with auto-merge without adding empirical safety
Migration note for existing consumers: if a consumer has already activated path-α + required_approvals > 0, document the PATCH command to transition to (2) cleanly

What this PR does NOT do

Does NOT change release-toolkit's own branch protection — that's a separate operator-authorized decision (this issue's surfacing point)
Does NOT modify the README — README is Herald's domain (#108); this is integration.md detail
Does NOT change the toolkit code — purely a documentation issue

Refs

Empirical surfacing 2026-06-26: path-α activated; PR #109 (manifest follow-up for v0.7.0) sits unmerged due to required_approvals: 1
AGENTS.md §8 Axis A worked instances (same session): merge_whitelist semantic + self-approval globally-blocked
Sibling docs: docs/integration.md §Branch protection compatibility (existing α/β/γ token-path doc), README #108 (Herald's domain — overview only)
Operator framing 2026-06-26: "documented decision per customer repository: either (3) or (2)"

## Why now The 2026-06-26 path-α activation surfaced an architectural constraint not previously documented: **Forgejo's branch-protection `required_approvals > 0` blocks the manifest follow-up PR's auto-merge**, even when `release-bot` is on `push_whitelist_usernames`. Empirical findings from the same session: - `merge_whitelist_usernames` is the wrong tool — it restricts WHO can merge when general merges are disabled; it doesn't bypass `required_approvals`. Empirical test: enabling it locked admin out of merging. - `enable_approvals_whitelist` + `approvals_whitelist_username` makes specific reviewers' approvals count as official, but doesn't allow the PR author to self-approve. - **Forgejo blocks self-approval globally** (`"approve your own pull is not allowed"` HTTP 422) — not a per-repo setting. Empirical test confirmed. So in stock Forgejo, the single-bot path-α design + a Forgejo-level review-gate are architecturally incompatible: the bot can't auto-merge its own PR if approval is required, and no native setting changes this. ## The tradeoff each consumer should explicitly decide | Option | `required_approvals` | Effort-to-cut | What's lost | |---|---|---|---| | **(2)** Zero-touch cuts | `0` | Workflow auto-merges manifest PR; operator clicks only Gate-1 (rolling PR) | Forgejo-level review-gate; chamber-level review-discipline still applies via convention | | **(3)** Operator-gated cuts | `1+` | Operator clicks Gate-1 (rolling PR) AND clicks the manifest follow-up PR | Manifest PR sits open for manual merge per cut | Other paths exist but are not recommended as defaults: - **(5) Two-bot pattern** — `release-bot` opens + merges; `release-reviewer` (separate bot) approves. Adds a second long-lived bot token. Operator surfaced this as "too heavy machinery" 2026-06-26. - **(1) Routine human approval** — a designated reviewer (e.g., the Surveyor chamber on alcatraz) routinely approves manifest PRs. Substrate-honest but adds a per-cut touch on someone else's surface. ## Scope of this issue Add a new section to `docs/integration.md` (probably under "Branch protection compatibility" alongside the existing α/β/γ token-path documentation): ### `## Branch protection: review-gate tradeoff` (proposed) 1. **Context**: explain why path-α's auto-merge interacts with Forgejo's `required_approvals` setting 2. **Empirical findings**: cite the §8 Axis A worked instances from 2026-06-26 (merge_whitelist semantic, self-approval blocked) so future readers don't re-investigate 3. **The (2) vs (3) tradeoff table**: as above 4. **Recommended default**: (2) for new consumers — the chamber-level review-discipline that has empirically load-borne the v0.4.0→v0.6.2 arc-convergence is sufficient; the Forgejo-level gate only adds an interaction with auto-merge without adding empirical safety 5. **Migration note for existing consumers**: if a consumer has already activated path-α + `required_approvals > 0`, document the PATCH command to transition to (2) cleanly ## What this PR does NOT do - Does NOT change release-toolkit's own branch protection — that's a separate operator-authorized decision (this issue's surfacing point) - Does NOT modify the README — README is Herald's domain (#108); this is integration.md detail - Does NOT change the toolkit code — purely a documentation issue ## Refs - **Empirical surfacing 2026-06-26**: path-α activated; PR #109 (manifest follow-up for v0.7.0) sits unmerged due to `required_approvals: 1` - **AGENTS.md §8 Axis A worked instances** (same session): merge_whitelist semantic + self-approval globally-blocked - **Sibling docs**: docs/integration.md §Branch protection compatibility (existing α/β/γ token-path doc), [README #108](https://git.frankenbit.de/frankenbit/release-toolkit/issues/108) (Herald's domain — overview only) - **Operator framing 2026-06-26**: "documented decision per customer repository: either (3) or (2)"

quartermaster referenced this issue

2026-06-26 14:33:12 +02:00

feat(release): auto-assign manifest follow-up PR to the user who merged the rolling PR #113

quartermaster referenced this issue

2026-06-26 14:37:28 +02:00

feat(release): configurable publish mode — draft-first (default) vs immediate-publish #114

quartermaster referenced this issue from a commit

2026-06-26 14:40:57 +02:00

docs(integration): document review-gate tradeoff (closes #112)

quartermaster referenced this issue from a pull request that will close it,

2026-06-26 14:52:03 +02:00

docs: AGENTS.md §8 Axis A n=7 across 5 surfaces — merge_whitelist + self-approval banks #115