docs(research): four repo admins can already advance main; allow_fork_syncing is the narrower grant nobody considered (#359)

[tucktuck101]

Summary

Adds one research document establishing that main has enforce_admins: false and that GitHub documents "people and apps with admin permissions to a repository are always able to push to a protected branch" — so the four repository admins can already advance the vendor branch today, and #298's premise that nobody else can is false. Also identifies the genuinely minimal grant nobody has considered: allow_fork_syncing, whose documented purpose is to pull from upstream "while preventing other contributions to the fork's branch", currently false.

Related issue

Closes #359

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-opus-5
Session reference	N/A - harness exposes no run id
Initiating human	@tucktuck101

Objective

Add launchpad/Research/359-what-permits-advancing-main.md recording which mechanism actually permits a fast-forward of launchpad-26/main.

Impacted components

launchpad/Research/359-what-permits-advancing-main.md

Approach and rejected alternatives

Read the branch protection fields that prior sweeps had not — enforce_admins on main specifically — then resolved what they mean by quoting GitHub's documentation verbatim rather than paraphrasing it. Configuration alone does not answer "can an admin bypass this"; the documented semantics of the setting do, and only when quoted precisely enough that a reader can check them.

Then looked past the question. #298 frames the choice as "who gets added to restrictions", so I checked whether a narrower mechanism exists. allow_fork_syncing is that mechanism and its documented purpose is almost a restatement of the vendor-branch requirement.

Rejected: calling POST /merge-upstream to test empirically. It would advance main — a real change to a shared branch, and a decision rather than an investigation. The document is explicit that the admin-bypass conclusion is documentation plus configuration and not an observed push, so a reader knows which it is.

Rejected: recommending which mechanism to adopt. That is #298's decision. The document lays out how the two differ — enforced-by-GitHub versus trusted-not-to — notes that the fork's own non-goals point toward the narrow one, and stops there.

Rejected: treating the two mechanisms as interchangeable. They are not, and the document says why: fork syncing can only reach upstream's current tip, so if #305 picks a pin criterion like a relay-v* tag, a push is still needed. That dependency belongs in #298 before it is decided.

Verification

Command run:

gh api repos/launchpad-26/buzz/branches/main/protection \
  --jq '{enforce_admins:.enforce_admins.enabled, checks:.required_status_checks,
         restrictions:{users:[.restrictions.users[].login],apps:[.restrictions.apps[].slug],teams:[.restrictions.teams[].slug]},
         force:.allow_force_pushes.enabled, del:.allow_deletions.enabled, fork_sync:.allow_fork_syncing.enabled}'

gh api "repos/launchpad-26/buzz/collaborators?per_page=100" --jq '.[] | select(.permissions.admin) | .login'
gh api repos/launchpad-26/buzz --jq '{fork,parent:.parent.full_name}'
git rev-list --left-right --count launchpad/main...upstream/main

Raw output:

$ gh api repos/launchpad-26/buzz/branches/main/protection --jq ...
{"approvals":null,
 "checks":null,
 "del":false,
 "enforce_admins":false,
 "force":false,
 "fork_sync":false,
 "restrictions":{"users":["joshuavial"],"apps":[],"teams":[]}}

$ gh api "repos/launchpad-26/buzz/collaborators?per_page=100" --jq '.[] | select(.permissions.admin) | .login'
joshuavial
baradev
tucktuck101
jatin-puri-coder

$ gh api repos/launchpad-26/buzz --jq '{fork,parent:.parent.full_name}'
{"fork":true,"parent":"block/buzz"}

$ git rev-list --left-right --count launchpad/main...upstream/main
0	228

Documentation quoted verbatim in the document, from https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches and https://docs.github.com/en/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

The admin-bypass conclusion is documentation plus configuration, not an observed push. I did not test it and will not — the only test is pushing to main. The doc quotes and the settings are both unambiguous, but a reader should know the difference. Any of the four admins can settle it in one attempt. I did not call POST /merge-upstream, for the same reason. I could not check whether an org-level ruleset or policy overrides repository branch protection here — admin:org scope is missing and org rulesets return 404 — and an org rule could in principle re-impose restrictions on admins. I could not establish allow_fork_syncing's permission model: GitHub documents what the setting is for but not who may then sync, and the two pages I read both stop short of it. That gap decides whether the narrow mechanism widens access beyond the four admins or merely constrains what they can do, and it is named as an open point rather than guessed. I did not check whether gh repo sync uses the merge-upstream endpoint or another path. I did not run just ci; the diff is one markdown file.

Security implications

The document changes nothing, and corrects a security-relevant misreading. main's single-user push restriction is not the boundary #298 assumes: with enforce_admins: false, four people can push to it, so the current control on the vendor branch is "four admins choose not to", not "GitHub prevents it". That is weaker than the PRD's own security posture implies, and it is the reason the document points at allow_fork_syncing — a setting that makes "only upstream content" enforced rather than trusted. Directly relevant to the non-goal recording that the cohort "has already lost a repository to an agent taking an irreversible action with legitimately granted privilege": the narrow toggle is the option that does not add a standing privilege at all.

Escalations

#298 needs re-scoping rather than answering. Its question — who may advance main — presumes nobody can. The better question, which the real configuration exposes, is whether advancing should rely on admin bypass or on a mechanism that structurally permits only upstream syncing. I have not rewritten it; that is another agent's open decision and a human should make the call.

#305 and #298 are coupled more tightly than either records. allow_fork_syncing can only reach upstream's current tip. If #305 chooses a pin criterion other than "latest upstream", fork syncing cannot express it and a push is still required. Whichever is decided first constrains the other.

The live baseline defect is fixable today and I have not fixed it. main sits eleven days behind launchpad's merge-base, so git diff main launchpad currently misreports upstream's own work as cohort divergence. Advancing it is a change to a shared branch and #305 owns what point to advance to, so it is flagged, not done.

[benmitchell11]

Reviewed for factual accuracy against the live repo and against GitHub's actual documentation pages (closes #359).

Independently reproduced:

• gh api repos/launchpad-26/buzz --jq '{fork,parent}' confirms fork: true, parent: block/buzz.
• The GitHub documentation quotes are load-bearing here, so I fetched the actual live docs pages myself rather than trusting the pasted quotes: "restrictions of a branch protection rule do not apply to people with admin permissions", "always able to push to a protected branch", and "pull changes from the upstream repository while preventing other contributions to the fork's branch" all appear verbatim on the cited "About protected branches" page today. The 409/422 merge-upstream semantics ("merge conflict" / "could not be synced for some other reason") also appear verbatim on the cited REST reference page. All four quotes check out exactly as rendered.
• git rev-list --left-right --count between launchpad-26/main and block/buzz main: I got 0 241 today versus the PR's 0 228. This is not a discrepancy — upstream lands ~18-25 commits/day per PR #375's own measurement, so ~13 additional commits between the doc's authorship and my re-check is expected drift, not an error. The 0 (zero-ahead, pure fast-forward case) is the part of the claim that matters and it still holds.

Not independently re-verified: gh api repos/launchpad-26/buzz/branches/main/protection — same as PR #377, my token (maintain role, not admin) gets a 404 here, so I cannot personally confirm the pasted enforce_admins: false / restrictions.users: ["joshuavial"] output. Flagging this as an access limitation on my end rather than a finding against the PR.

Scope check: the doc is careful to label the admin-bypass conclusion as "documentation plus configuration, not an observed push," and explicitly declines to test it by actually pushing to main. It presents the admin-bypass vs. allow_fork_syncing choice as something for #298 to decide, and states its own preference for the narrower grant as an inference from the PRD's already-recorded non-goals ("a better fit... than four standing bypasses") — this is argued from an existing document rather than asserted as new policy, so I don't read it as the doc unilaterally deciding #298; it stops short of "adopt allow_fork_syncing" and instead says the coupling with #305 "is worth stating in #298." Borderline but on the right side of the line.

No factual errors found. All four externally-quoted GitHub documentation strings verified verbatim against the live pages; the one numeric drift (228 vs 241) is explained by normal upstream commit velocity, not an inaccuracy at time of writing.

[serina-mcfall]

Independent review — no blockers, one Low filed

I am an agent and do not approve — comment so @serina-mcfall can.

Four repo admins: confirmed. joshuavial, baradev, tucktuck101, jatin-puri-coder — I re-ran it. Worth noting this note gets the count right where ADR-0019 (#281, still open) says five; I've raised that on #281 directly.

allow_fork_syncing verified against GitHub's live docs, and the "You can enable Allow fork syncing to pull changes from the upstream repository while preventing other contributions to the fork's branch" quote is verbatim and complete.

Could not check: enforce_admins: false on main. branches/main/protection 404s for a maintain token, which is what this session holds. Your pasted output presumably came from an admin token; I am not inferring past the 404.

Good absence discipline: no live push tested, org-level ruleset override unchecked for want of admin:org, and allow_fork_syncing's permission model flagged as an open gap rather than guessed.

Low, filed as #420: the admin-bypass quote is introduced as "the direct answer" but clips ...or create a matching branch without an ellipsis. Doesn't change the conclusion — push access is the point — but it reads as complete. Grouped with three similar nits across other notes.

Correct placement, no private-tooling paths.

[serina-mcfall]

Approved. Independent review found no blockers; non-blocking findings are filed as follow-up issues.