fix(release): require full v* coverage from the tag ruleset and fail on API errors

A tag ruleset counts only with no exclusions and, where GitHub shows its bypass
list, only admin bypass. A missing environment is a setup gap only on a 404;
any other API failure now fails the plan instead of reading as a gap.

Author: thymikee

scripts/__tests__/release-plan.test.ts

@@ -163,6 +163,35 @@ test('each missing protection is named on its own', () => {
     tagRulesets: [{ ...setup.tagRulesets[0], enforcement: 'evaluate' }],
   };
   assert.match(repositorySetupGaps(evaluating).join(), /tag ruleset/);
+  const anyBranchToggle = {
+    ...setup,
+    npmPublish: { deployment_branch_policy: { custom_branch_policies: false } },
+  };
+  assert.match(repositorySetupGaps(anyBranchToggle).join(), /npm-publish environment/);
+  const excluding = {
+    ...setup,
+    tagRulesets: [
+      {
+        ...setup.tagRulesets[0],
+        conditions: { ref_name: { include: ['refs/tags/v*'], exclude: ['refs/tags/v9*'] } },
+      },
+    ],
+  };
+  assert.match(repositorySetupGaps(excluding).join(), /tag ruleset/);
+  const writerBypass = {
+    ...setup,
+    tagRulesets: [
+      { ...setup.tagRulesets[0], bypass_actors: [{ actor_type: 'RepositoryRole', actor_id: 4 }] },
+    ],
+  };
+  assert.match(repositorySetupGaps(writerBypass).join(), /tag ruleset/);
+  const adminBypass = {
+    ...setup,
+    tagRulesets: [
+      { ...setup.tagRulesets[0], bypass_actors: [{ actor_type: 'RepositoryRole', actor_id: 5 }] },
+    ],
+  };
+  assert.deepEqual(repositorySetupGaps(adminBypass), []);
   const creatable = {
     ...setup,
     tagRulesets: [{ ...setup.tagRulesets[0], rules: [{ type: 'deletion' }] }],

scripts/release-plan.mjs

@@ -108,20 +108,39 @@ export function repositorySetupGaps({ npmPublish, npmPublishPolicies, release, t
   const reviewers = release?.protection_rules?.find((rule) => rule.type === 'required_reviewers');
   if (!reviewers?.reviewers?.length) gaps.push('the release environment must require a reviewer');
   if (!tagRulesets.some(guardsReleaseTags)) {
-    gaps.push('an active tag ruleset must restrict creating, updating, and deleting refs/tags/v*');
+    gaps.push(
+      'an active tag ruleset must restrict creating, updating, and deleting every refs/tags/v* tag, ' +
+        'with no exclusions and only admins able to bypass',
+    );
   }
   return gaps;
 }
 
+/**
+ * A ruleset covers every `v*` tag only with no exclusions. GitHub returns `bypass_actors` only to
+ * admins, never to the Plan job's token, so the admin-only bypass is checked where it is visible.
+ */
 function guardsReleaseTags(ruleset) {
   const types = new Set(ruleset.rules.map((rule) => rule.type));
+  const refs = ruleset.conditions?.ref_name;
   return (
     ruleset.enforcement === 'active' &&
-    ruleset.conditions?.ref_name?.include?.includes('refs/tags/v*') &&
-    ['creation', 'update', 'deletion'].every((type) => types.has(type))
+    (refs?.include?.includes('refs/tags/v*') || refs?.include?.includes('~ALL')) &&
+    (refs.exclude ?? []).length === 0 &&
+    ['creation', 'update', 'deletion'].every((type) => types.has(type)) &&
+    (ruleset.bypass_actors ?? []).every(isAdminBypass)
+  );
+}
+
+function isAdminBypass(actor) {
+  return (
+    actor.actor_type === 'OrganizationAdmin' ||
+    (actor.actor_type === 'RepositoryRole' && actor.actor_id === REPOSITORY_ADMIN_ROLE)
   );
 }
 
+const REPOSITORY_ADMIN_ROLE = 5;
+
 function assertAheadOfStable(run, version) {
   if (run.latestStable && compareReleaseVersions(version, run.latestStable) <= 0) {
     throw new Error(
@@ -195,18 +214,30 @@ async function github(env, pathname) {
       authorization: `Bearer ${env.GITHUB_TOKEN}`,
     },
   });
-  if (!response.ok) throw new Error(`GitHub API ${pathname} failed: ${response.status}`);
+  if (!response.ok) {
+    throw Object.assign(new Error(`GitHub API ${pathname} failed: ${response.status}`), {
+      status: response.status,
+    });
+  }
   return response.json();
 }
 
+/** A missing environment is a setup gap; any other failure must not read as one. */
+function absentOn404(fallback) {
+  return (error) => {
+    if (error.status === 404) return fallback;
+    throw error;
+  };
+}
+
 async function readRepositorySetup(env) {
-  const environment = (name) => github(env, `environments/${name}`).catch(() => null);
+  const environment = (name) => github(env, `environments/${name}`).catch(absentOn404(null));
   const summaries = await github(env, 'rulesets?targets=tag');
   return {
     npmPublish: await environment('npm-publish'),
     npmPublishPolicies: await github(env, 'environments/npm-publish/deployment-branch-policies')
       .then((body) => body.branch_policies)
-      .catch(() => []),
+      .catch(absentOn404([])),
     release: await environment('release'),
     tagRulesets: await Promise.all(
       summaries.map((summary) => github(env, `rulesets/${summary.id}`)),