fix(docs): the numeric-id role narrows grants, it does not split buckets

An audit of the previous commit cleared it — role matching in core is exact
map lookup with no wildcard, no consumer parses roles expecting a
`github:org/` shape, the numeric id arrives on the same authenticated
`/user` body as the login so it is no more forgeable, and a hostile org
literally named `id/5` yields `github:org/id/5`, not `github:id/5`.

But it caught my doc comment overclaiming. Binding to `github:id/<id>`
protects the GRANT side: an impostor who re-registers a released handle
carries a different numeric role, so an exact-match binding does not follow
them. It does NOT separate the BUCKETS. The enforcement subject is still
`principal.id`, so the re-registered handle keeps landing on the same
`user:github:<login>` group, usage ledger and budget as the previous owner.
Splitting those means changing the principal id, which is the breaking
change this deliberately avoids — so the limit is now stated where an
operator reading the comment will see it, rather than implied fixed.

Also drops a test I added that was a strict subset of an existing one
covering the same two cases plus a positive control.

And gates this repo's release workflow on its test suite: `ci.yml` is armed
on branch pushes and PRs only, so a `v*` tag ran release.yml with no test
job in the graph at all, and the build-provenance attestation would have
certified the provenance of an untested artifact. The gate runs the repo's
own suite against the core SHA pinned in `.busbar-ref` — the commit the
release actually builds against, not a moving branch.

Author: matthew

.github/workflows/release.yml

@@ -28,9 +28,44 @@ permissions:
   attestations: write  # record the build-provenance attestation
 
 jobs:
+  # ── TEST GATE ────────────────────────────────────────────────────────────────────────────────
+  # Nothing is built, signed or attested until this repo's own suite passes AGAINST THE EXACT CORE
+  # COMMIT THIS RELEASE WILL BUILD AGAINST.
+  #
+  # This was missing, and the gap was not theoretical: `ci.yml` is armed on branch pushes and PRs
+  # only, so a `v*` tag event did not trigger it AT ALL, while `release-on-upstream.yml`'s cron cuts
+  # those tags automatically. A signed, provenance-attested plugin could therefore ship from a
+  # commit whose suite never ran in that run -- the attestation would faithfully certify the
+  # provenance of an untested artifact.
+  #
+  # `busbar_ref` is resolved from `.busbar-ref`, NOT from the branch: the release builds against a
+  # pinned core SHA, so the gate has to test against that same SHA or it is not testing what ships.
+  # Testing against a moving branch instead is the other half of the same defect.
+  resolve-busbar-ref:
+    runs-on: ubuntu-latest
+    outputs:
+      sha: ${{ steps.ref.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Resolve busbar ref from .busbar-ref
+        id: ref
+        run: echo "sha=$(cut -d' ' -f1 .busbar-ref)" >> "$GITHUB_OUTPUT"
+        shell: bash
+
+  gate:
+    needs: resolve-busbar-ref
+    uses: GetBusbar/busbar/.github/workflows/plugin-ci.yml@dev
+    with:
+      plugin_crate: busbar-auth-github-plugin
+      plugin_kind: auth
+      plugin_alias: github
+      service: wiremock
+      busbar_ref: ${{ needs.resolve-busbar-ref.outputs.sha }}
+
   # Create the Release first so the parallel per-target upload jobs have something to attach to
   # (uploading from a matrix without a pre-existing release races -> "release not found").
   create-release:
+    needs: gate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7

busbar-auth-github/src/lib.rs

@@ -405,11 +405,20 @@ pub fn parse_org_groups(body: &str) -> Option<Vec<String>> {
 /// anywhere reporting a change of person.
 ///
 /// So the stable numeric account id is emitted ALONGSIDE, as the `github:id/<id>` role. That is
-/// purely additive: every existing login binding keeps working untouched, and an operator who wants
-/// an identifier that cannot be transferred can bind to `github:id/12345` and migrate at their own
-/// pace. New deployments should prefer it. The same reasoning applies to `github:org/<org>`, which is
-/// likewise a renameable slug, but GitHub's `/user/orgs` entries are reduced to their login here and
-/// closing that one needs a payload change rather than a one-line addition.
+/// purely additive: every existing login binding keeps working untouched, and an operator can bind to
+/// `github:id/12345` and migrate at their own pace. New deployments should prefer it.
+///
+/// WHAT THIS DOES AND DOES NOT FIX, because the difference is easy to overread. It narrows WHO GETS
+/// GRANTED: a binding on `github:id/<id>` cannot be inherited by whoever re-registers the handle,
+/// because core matches roles by exact lookup and the impostor carries a different numeric role. It
+/// does NOT separate the BUCKETS: the enforcement subject is still `principal.id`, so the
+/// re-registered handle continues to land on the same `user:github:<login>` group, usage ledger and
+/// budget as its previous owner. Separating those means changing the principal id, which is the
+/// breaking change this deliberately avoids.
+///
+/// `github:org/<org>` has the same weakness, being likewise a renameable slug. Closing that one needs
+/// the org's numeric id threaded through `parse_org_groups`, a payload change rather than a one-line
+/// addition.
 pub fn build_principal(user: &GhUser, org_groups: Vec<String>) -> Principal {
     let mut p = Principal::from_id(format!("github:{}", user.login));
     p.name = Some(user.name.clone().unwrap_or_else(|| user.login.clone()));

busbar-auth-github/src/tests.rs

@@ -749,10 +749,3 @@ fn the_stable_numeric_id_distinguishes_two_accounts_sharing_one_handle() {
         b.roles
     );
 }
-
-/// A `/user` body with no numeric `id` still fails closed, as it always did.
-#[test]
-fn a_user_body_without_a_numeric_id_is_rejected() {
-    assert!(parse_user(r#"{"login":"octocat"}"#).is_none());
-    assert!(parse_user(r#"{"login":"octocat","id":"not-a-number"}"#).is_none());
-}