Files
ersatztv/docs/decisions/records/release/main-direct-push-disabled.md
T
timothyandClaude Opus 5 6d80343320 fix(743): close the admin force-merge bypass; the push half alone was not enough
Independent review found the record repeated on the merge path exactly the
mistake it had just diagnosed on the push path.

The push argument was: a whitelist naming `timothy` closes nothing, because
`timothy` is the identity every credential already holds. The merge path had
the identical shape and went unchecked — `block_admin_merge_override` defaults
to `false`, so `CanBypassBranchProtection` returns true for a repo admin and
`POST /pulls/{n}/merge` with `force_merge: true` merges straight past a missing
or red `review-verdict/h10`. One API call, no forgery, no PATCH — cheaper than
the push route this change had just removed.

So `enable_push: false` alone did NOT make the gate load-bearing, which is
what the record's headline sentence claimed. `main` now carries both fields;
they are one control and neither is citable alone.

An admin-shaped control that exempts the only admin exempts everybody.

Other review findings addressed:

- H11's owning record (`release.format-as-you-touch-rebase`) now documents the
  #719 tag-only carve-out. It is a narrowing of an existing convention, so it
  amends that record rather than adding a new one — including the two details
  that are easy to regress (the .husky/pre-push forwarding, without which the
  exemption is dead code the unit tests still pass over; and the at-least-one-
  ref guard against vacuous exemption).
- The record now states which write surfaces were enumerated and how each was
  established — contents-API refusal is MEASURED here (403 `user cannot commit
  to repo`), apply-patch/revert/cherry-pick are source-attested only. The
  admin force-merge bypass is likewise marked source-attested, not probed:
  probing it means merging an unreviewed PR.
- prepush-rebase-check.sh: process a final ref line with no trailing newline
  (previously dropped, which silently reinstated the #719 block), and skip the
  stdin read on a TTY so an interactive run does not hang.
- Corrected a citation the review caught: docs/ci-cd.md documents the tag step,
  not a release-notes-PR flow. Cite #719 for the observed flow instead.

Also fixed a frontmatter break this round introduced: a `: ` inside the
unquoted `rule:` scalar. PyYAML rejected it while the dependency-free reader
accepted it, so only `scripts/tests` caught it.

Verification: 438/438 script tests pass; decisions-validate OK; PyYAML parses
all three touched records.

refs #743 #719

Decisions-Edit: yes
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 23:52:28 +02:00

9.2 KiB

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
key title status since supersedes superseded-by rule signals mechanics
release.main-direct-push-disabled 2026-08-05 — `main` refuses direct pushes (`enable_push: false`), because a push whitelist would have been a no-op here (#743) active 2026-08-05 none none Branch protection on `main` carries `enable_push: false` AND `block_admin_merge_override: true`. Both halves are required and neither is sufficient. `enable_push: false` removes the direct-push path, leaving the PR merge path — the only path on which Gitea evaluates `status_check_contexts`, and therefore the only path on which `review-verdict/h10` is consulted at all. `block_admin_merge_override: true` then closes the force-merge bypass on that remaining path: with it false (the default), `CanBypassBranchProtection` returns true for a repo admin, so `POST /pulls/{n}/merge` with `force_merge: true` merges a PR whose `h10` is missing or red — one API call, no forgery, no PATCH. Do NOT "soften" the push half to a push WHITELIST: measured here, a whitelist naming `timothy` still admits the push, and `timothy` is the identity every agent session, PAT and injected `GITEA_TOKEN` already acts as, so the whitelist form closes nothing while reading in review as a control. Same reasoning is why the admin-override half is needed: an admin-shaped control that exempts the only admin exempts everybody. What remains open: a credential that can PATCH branch protection off can still undo either half — an accepted residual, not a closed route. Tag pushes are unaffected (`tag_protections` governs those separately), so the release cut still works. direct push to main, push whitelist, enable_push false, branch protection bypass, review-verdict/h10 bypassable without forging, merge consent derived not asserted, pre-receive hook declined, Not allowed to push to protected branch, protected branch, tag_protections, release tag push, GITEA_TOKEN repo write, RENOVATE_TOKEN, site admin bypass, PR-only flow · paths: `docs/ci-cd.md` · issues: #743, #697, #698, #622, #672, #706, #742, server-management#714 Gitea 1.27.1. `PATCH /api/v1/repos/timothy/ersatztv/branch_protections/main` with `{"enable_push": false, "block_admin_merge_override": true}`; whitelist fields left off (`enable_push_whitelist: false`, empty arrays), `enable_force_push: false`, `enable_merge_whitelist: false`, `required_approvals: 0`. MEASURED 2026-08-05 against a throwaway `probe-743-*` rule rather than against `main`: with `enable_push: false` a push by `timothy` (site admin) was REFUSED — `pre-receive hook declined`, `Not allowed to push to protected branch`; after PATCHing the same rule to `enable_push: true` + `enable_push_whitelist: true` + `push_whitelist_usernames: ["timothy"]` the identical push SUCCEEDED. Separately probed on a second throwaway rule: a contents-API write (`PUT /repos/{o}/{r}/contents/{path}` with `branch` set to the protected branch) was REFUSED HTTP 403 `user cannot commit to repo [user: timothy]` — so the web-editor/API file-write surface does not bypass it either. Then on `main` itself: `git push origin HEAD:main` REFUSED, and a tag-only push SUCCEEDED from the same worktree. `GET .../tag_protections` returns `[]`; repo is `fork: false`, `mirror: false`. NOT measured, source-attested only (Gitea 1.27 `CanBypassBranchProtection`, `services/pull/check.go`, `routers/private/hook_pre_receive.go`): that `block_admin_merge_override: false` would have let an admin `force_merge` past the required contexts — the field was set to true rather than probed, since probing it means merging an unreviewed PR. All probe artifacts (two rules, two branches, one tag) deleted and confirmed gone; `origin/main` head unchanged at `08e95f9ec` throughout.

Why a whitelist was the wrong shape. #743 proposed "a push whitelist on main (or disable direct push entirely)" as if the two were interchangeable. They are not, and which one is right depends on a fact about this instance: the only accounts with repository write are timothy (a site admin) and renovate. Every credential in the threat model — an agent session, a collaborator PAT, the GITEA_TOKEN Gitea injects into every Actions job — authenticates as one of those two, and overwhelmingly as timothy. A whitelist admitting timothy therefore admits precisely the identity the control is supposed to constrain. It would have ticked the issue's box while changing nothing. This was measured, not reasoned: the same push was refused under enable_push: false and accepted under a whitelist naming timothy.

Disabling push alone was NOT enough, and the reason is the same argument twice. The first draft of this record disabled direct push and concluded that review-verdict/h10 was therefore load-bearing. An independent review caught that this repeated on the merge path exactly the mistake it had just diagnosed on the push path. The push argument was: a whitelist naming timothy fails because timothy is the identity every credential already holds. The merge path had the identical shape — block_admin_merge_override defaulted to false, so CanBypassBranchProtection returned true for a repo admin and POST /pulls/{n}/merge with force_merge: true merged straight past a missing or red h10. One API call, cheaper than the push route it replaced. An admin-shaped control that exempts the only admin exempts everybody. Both fields are now set; treat them as one control, and never cite enable_push: false alone as the reason the gate holds.

What this actually closes, and what it does not. It closes the write-only credential routes, which is most of #743's own "who can do it" list: the injected GITEA_TOKEN (repo write, not admin), RENOVATE_TOKEN, and any non-admin collaborator PAT. Those can no longer reach main at all, by any path that skips the gate.

It does not close the admin route. timothy is a site admin, so a credential holding that identity can PATCH either field off, act, and restore it — the exact sequence used to prove the push semantics above. Closing that requires agent sessions to run as a scoped non-admin credential, which is a different change with its own cost (packages live in a user namespace; see the "Admin ownership is a real residual" section of ci.actions-credential-scoping). Recorded as an accepted residual rather than fixed here, so it is not mistaken for covered. The severity bound from #697 and #743 is unchanged throughout: push access is required, so this is a compromised contributor or a subverted automated session, never an anonymous attacker.

Which write surfaces were enumerated. git push (measured, refused), the contents API and by extension the web editor / upload path (measured on a probe branch, refused HTTP 403 — they share the CanUserPush predicate, which has no admin special-case and no unprotected_file_patterns carve-out since that field is empty), apply-patch / revert / cherry-pick (source-attested, same predicate), force push (enable_force_push: false), default-branch deletion (separately refused), and fork-sync / mirror (not applicable: fork: false, mirror: false). Merge remains the one intended path.

Why the release cut does not deadlock. #743 flagged that the tag path had to keep working, and #719 documents H11 blocking a tag-only push on every release cut. Branch protection is scoped to refs/heads/main; tags are governed by an entirely separate mechanism, and tag_protections on this repo is empty, so tag pushes are unrestricted by anything except ordinary write permission. Demonstrated rather than assumed: from one worktree, the branch push to main was refused and a tag push succeeded. Do not conflate the two mechanisms — disabling branch push says nothing about tags, and a future tag-protection rule would not inherit from this one.

The docker-build.yml persist-credentials question (#743's fourth box), decided and deferred. Its six actions/checkout steps omit persist-credentials: false, so a head-resolved job keeps a write-capable credential in .git/config. It should be set — but not blind, and not in this PR, because two steps run git fetch --no-tags --depth=100 origin "$base_ref" || true and feed the result into the changed-file skip logic. That || true means a credential regression does not fail the job; it silently yields an empty changed-file set, and the skip logic then reads "nothing changed". The repo is public, so anonymous fetch is expected to cover it — expected is not measured, and the failure mode is silent, which is the shape that has burned this repo before. The correct order is: drop the || true masking so a fetch failure is loud, then set persist-credentials: false and confirm both jobs still compute a non-empty changed set on a PR that genuinely changes files.

Why this is not redundant with the Husky pre-push hooks. .husky/pre-push guards (H6 done-when, H11 rebase, H13 clean worktree) are client-side and deliberately fail-open — a git hook cannot prompt. They are not installed in CI, not present in a fresh clone until husky runs, and --no-verify bypasses them, which the worktree workflow uses routinely. They are good friction against mistakes and were never a control against a credential. This record is the server-side half; the hooks remain useful and unchanged.