@catladder/cli 0.0.0-main-a6b45abe → 0.0.0-main-bd7c0346

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-main-a6b45abe",
+  "version": "0.0.0-main-bd7c0346",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",

package/src/apps/cli/commands/project/__tests__/githubMergeGating.test.ts

@@ -0,0 +1,112 @@
+import { AGGREGATE_CHECK_JOB_NAME } from "@catladder/pipeline";
+import { describe, expect, it } from "vitest";
+import {
+  desiredMergeGatingRuleset,
+  GITHUB_ACTIONS_APP_ID,
+  rulesetProvidesMergeGating,
+} from "../githubMergeGating";
+
+const asRuleset = (overrides: object = {}) => ({
+  id: 1,
+  ...desiredMergeGatingRuleset(),
+  ...overrides,
+});
+
+describe("desiredMergeGatingRuleset", () => {
+  it("requires the aggregate check on the default branch", () => {
+    const ruleset = desiredMergeGatingRuleset();
+    expect(ruleset.enforcement).toBe("active");
+    expect(ruleset.conditions.ref_name.include).toEqual(["~DEFAULT_BRANCH"]);
+    expect(ruleset.rules).toEqual([
+      expect.objectContaining({
+        type: "required_status_checks",
+        parameters: expect.objectContaining({
+          required_status_checks: [
+            {
+              context: AGGREGATE_CHECK_JOB_NAME,
+              integration_id: GITHUB_ACTIONS_APP_ID,
+            },
+          ],
+        }),
+      }),
+    ]);
+  });
+
+  it("lets the release job (actions app) bypass the gating", () => {
+    expect(desiredMergeGatingRuleset().bypass_actors).toEqual([
+      {
+        actor_id: GITHUB_ACTIONS_APP_ID,
+        actor_type: "Integration",
+        bypass_mode: "always",
+      },
+    ]);
+  });
+
+  it("satisfies its own predicate", () => {
+    expect(rulesetProvidesMergeGating(asRuleset())).toBe(true);
+  });
+});
+
+describe("rulesetProvidesMergeGating", () => {
+  it("rejects a disabled ruleset", () => {
+    expect(
+      rulesetProvidesMergeGating(asRuleset({ enforcement: "disabled" })),
+    ).toBe(false);
+  });
+
+  it("rejects a ruleset without the aggregate check", () => {
+    expect(rulesetProvidesMergeGating(asRuleset({ rules: [] }))).toBe(false);
+    expect(
+      rulesetProvidesMergeGating(
+        asRuleset({
+          rules: [
+            {
+              type: "required_status_checks",
+              parameters: {
+                required_status_checks: [{ context: "some other check" }],
+              },
+            },
+          ],
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it("rejects a ruleset whose release-job bypass is missing or weakened", () => {
+    expect(rulesetProvidesMergeGating(asRuleset({ bypass_actors: [] }))).toBe(
+      false,
+    );
+    expect(
+      rulesetProvidesMergeGating(
+        asRuleset({
+          bypass_actors: [
+            {
+              actor_id: GITHUB_ACTIONS_APP_ID,
+              actor_type: "Integration",
+              bypass_mode: "pull_request",
+            },
+          ],
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it("accepts extra rules and bypass actors alongside ours", () => {
+    const desired = desiredMergeGatingRuleset();
+    expect(
+      rulesetProvidesMergeGating(
+        asRuleset({
+          rules: [{ type: "deletion" }, ...desired.rules],
+          bypass_actors: [
+            {
+              actor_id: 5,
+              actor_type: "RepositoryRole",
+              bypass_mode: "always",
+            },
+            ...desired.bypass_actors,
+          ],
+        }),
+      ),
+    ).toBe(true);
+  });
+});

package/src/apps/cli/commands/project/doctor/checkGithub.ts

@@ -16,6 +16,11 @@ import {
   listGithubSecretNames,
   listGithubVariableNames,
 } from "../../../../../utils/github";
+import type { GithubRuleset } from "../githubMergeGating";
+import {
+  MERGE_GATING_RULESET_NAME,
+  rulesetProvidesMergeGating,
+} from "../githubMergeGating";
 import type { DoctorReport } from "./DoctorReport";
 
 /** marker for repo-level (environment-less) targets, see collectSecretTargets */
@@ -161,10 +166,13 @@ export const checkGithub = async (report: DoctorReport, config: Config) => {
 
 /**
  * verifies the merge gating `project setup` configures: auto-merge
- * enabled and the generated `catladder ✅` aggregate check required on
- * the default branch. Without it a PR is mergeable while its checks
- * are still running — gitlab ships this behavior built-in, github
- * silently does not.
+ * enabled and the `catladder merge gating` ruleset requiring the
+ * generated `catladder ✅` aggregate check on the default branch (with
+ * the bypass that lets the release job push). Without the check a PR
+ * is mergeable while its checks are still running — gitlab ships this
+ * behavior built-in, github silently does not. The check required via
+ * classic branch protection instead is flagged: that setup rejects the
+ * release job's own push (GH006).
  */
 const checkGithubMergeGating = async (report: DoctorReport, repo: string) => {
   let repoInfo: { default_branch: string; allow_auto_merge: boolean };
@@ -184,6 +192,36 @@ const checkGithubMergeGating = async (report: DoctorReport, repo: string) => {
   }
 
   const branch = repoInfo.default_branch;
+  let rulesets: Array<{ id: number; name: string }>;
+  try {
+    rulesets = await ghApiJson("GET", `repos/${repo}/rulesets?per_page=100`);
+  } catch (e) {
+    report.warn(`could not list rulesets of ${repo} (${e.message})`);
+    return;
+  }
+  const named = rulesets.find((r) => r.name === MERGE_GATING_RULESET_NAME);
+  const ruleset = named
+    ? await ghApiJson<GithubRuleset>(
+        "GET",
+        `repos/${repo}/rulesets/${named.id}`,
+      ).catch(() => null)
+    : null;
+  if (ruleset && rulesetProvidesMergeGating(ruleset)) {
+    report.ok(
+      `ruleset '${MERGE_GATING_RULESET_NAME}': '${AGGREGATE_CHECK_JOB_NAME}' required on ${branch}, release job can push`,
+    );
+  } else if (ruleset) {
+    report.fail(
+      `ruleset '${MERGE_GATING_RULESET_NAME}' exists but is incomplete (inactive, check not required, or release-job bypass missing)`,
+      "run: catladder project setup",
+    );
+  } else {
+    report.fail(
+      `no '${MERGE_GATING_RULESET_NAME}' ruleset on ${repo} — PRs can merge while the pipeline is red or still running`,
+      "run: catladder project setup",
+    );
+  }
+
   const protection = await ghApiJson<any>(
     "GET",
     `repos/${repo}/branches/${branch}/protection`,
@@ -191,17 +229,15 @@ const checkGithubMergeGating = async (report: DoctorReport, repo: string) => {
   const checks: Array<{ context: string }> =
     protection?.required_status_checks?.checks ?? [];
   if (checks.some((c) => c.context === AGGREGATE_CHECK_JOB_NAME)) {
-    report.ok(`'${AGGREGATE_CHECK_JOB_NAME}' required on ${branch}`);
-  } else {
     report.fail(
-      `'${AGGREGATE_CHECK_JOB_NAME}' is not a required check on ${branch} — PRs can merge while the pipeline is red or still running`,
+      `'${AGGREGATE_CHECK_JOB_NAME}' is still required via classic branch protection on ${branch} — that rejects the release job's push (GH006)`,
       "run: catladder project setup",
     );
   }
   const stale = checks.filter((c) => c.context !== AGGREGATE_CHECK_JOB_NAME);
   if (stale.length > 0) {
     report.warn(
-      `${branch} requires ${stale.length} additional named check(s) (${stale
+      `${branch} requires ${stale.length} additional named check(s) via classic branch protection (${stale
         .map((c) => c.context)
         .join(
           ", ",

package/src/apps/cli/commands/project/githubMergeGating.ts

@@ -0,0 +1,90 @@
+import { AGGREGATE_CHECK_JOB_NAME } from "@catladder/pipeline";
+
+/**
+ * github merge gating — shared between `project setup` (writes it) and
+ * `project doctor` (verifies it).
+ *
+ * The gating lives in a repository RULESET, not classic branch
+ * protection: only rulesets can carry bypass actors, and the release
+ * job needs one. It pushes the release commit and tag straight to the
+ * default branch with the workflow token — under classic protection
+ * the required `catladder ✅` check rejects that push (GH006), because
+ * the fresh release commit cannot have a passing check yet. The bypass
+ * covers the GitHub Actions app, i.e. pushes made by workflows, while
+ * PRs and humans stay gated. (Gitlab's counterpart is the
+ * maintainer-role project access token, which may push to protected
+ * branches by default — the same trade-off, made by the platform.)
+ */
+
+/** the app id of GitHub Actions — the actor workflow tokens act as */
+export const GITHUB_ACTIONS_APP_ID = 15368;
+
+export const MERGE_GATING_RULESET_NAME = "catladder merge gating";
+
+export type GithubRuleset = {
+  id: number;
+  name: string;
+  enforcement: string;
+  rules?: Array<{
+    type: string;
+    parameters?: {
+      required_status_checks?: Array<{ context: string }>;
+    };
+  }>;
+  bypass_actors?: Array<{
+    actor_id?: number | null;
+    actor_type: string;
+    bypass_mode: string;
+  }>;
+};
+
+/** the ruleset `project setup` creates (and restores on drift) */
+export const desiredMergeGatingRuleset = () => ({
+  name: MERGE_GATING_RULESET_NAME,
+  target: "branch",
+  enforcement: "active",
+  conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+  rules: [
+    {
+      type: "required_status_checks",
+      parameters: {
+        strict_required_status_checks_policy: false,
+        do_not_enforce_on_create: false,
+        required_status_checks: [
+          {
+            context: AGGREGATE_CHECK_JOB_NAME,
+            integration_id: GITHUB_ACTIONS_APP_ID,
+          },
+        ],
+      },
+    },
+  ],
+  bypass_actors: [
+    {
+      actor_id: GITHUB_ACTIONS_APP_ID,
+      actor_type: "Integration",
+      bypass_mode: "always",
+    },
+  ],
+});
+
+/**
+ * whether a ruleset provides working merge gating: active, requires
+ * the aggregate check, and lets the release job (GitHub Actions app)
+ * bypass it. Extra rules or bypass actors someone added are fine.
+ */
+export const rulesetProvidesMergeGating = (ruleset: GithubRuleset): boolean =>
+  ruleset.enforcement === "active" &&
+  (ruleset.rules ?? []).some(
+    (rule) =>
+      rule.type === "required_status_checks" &&
+      (rule.parameters?.required_status_checks ?? []).some(
+        (check) => check.context === AGGREGATE_CHECK_JOB_NAME,
+      ),
+  ) &&
+  (ruleset.bypass_actors ?? []).some(
+    (actor) =>
+      actor.actor_type === "Integration" &&
+      actor.actor_id === GITHUB_ACTIONS_APP_ID &&
+      actor.bypass_mode === "always",
+  );

package/src/apps/cli/commands/project/setup/setupGithub.ts

@@ -7,6 +7,12 @@ import {
 import { getConfiguredGithubRepo } from "../../../../../commands/project/commandSecretsSyncGithub";
 import type { IO } from "../../../../../core/types";
 import { ghApiJson, isGhAuthenticated } from "../../../../../utils/github";
+import type { GithubRuleset } from "../githubMergeGating";
+import {
+  desiredMergeGatingRuleset,
+  MERGE_GATING_RULESET_NAME,
+  rulesetProvidesMergeGating,
+} from "../githubMergeGating";
 
 /**
  * configures github merge gating — the sane default gitlab ships
@@ -15,15 +21,17 @@ import { ghApiJson, isGhAuthenticated } from "../../../../../utils/github";
  * auto-merge button never appears.
  *
  * - repo settings: allow auto-merge, delete merged head branches
- * - branch protection on the default branch: require the generated
+ * - a repository ruleset on the default branch requiring the generated
  *   `catladder ✅` aggregate check (the one stable context — individual
- *   job names change with every component add/rename)
+ *   job names change with every component add/rename), with a bypass
+ *   for the GitHub Actions app so the release job can push the release
+ *   commit and tag (see githubMergeGating.ts for the full rationale)
  *
- * Deliberately non-destructive: existing protection settings
- * (enforce-admins, required reviews, restrictions, strictness) are
- * preserved; the aggregate context is merged into the required checks
- * rather than replacing them. Admins can still bypass per PR — this is
- * a default, not a cage.
+ * Earlier versions required the check via classic branch protection,
+ * which has no bypass list — the release job's direct push to the
+ * default branch bounced off catladder's own gating (GH006). Setup
+ * migrates that away: the aggregate context is removed from an
+ * existing classic rule, everything else in it is preserved.
  */
 export const setupGithub = async (instance: IO, config: Config) => {
   if (!getEnabledPipelineTypes(config).includes("github")) {
@@ -60,33 +68,99 @@ export const setupGithub = async (instance: IO, config: Config) => {
   }
 
   const branch = repoInfo.default_branch;
+  const rulesets = await ghApiJson<Array<{ id: number; name: string }>>(
+    "GET",
+    `repos/${repo}/rulesets?per_page=100`,
+  );
+  const existing = rulesets.find((r) => r.name === MERGE_GATING_RULESET_NAME);
+  if (!existing) {
+    await ghApiJson(
+      "POST",
+      `repos/${repo}/rulesets`,
+      desiredMergeGatingRuleset(),
+    );
+    instance.log(
+      `✅ ruleset '${MERGE_GATING_RULESET_NAME}': '${AGGREGATE_CHECK_JOB_NAME}' required on ${branch} — merges wait for the pipeline, the release job can push`,
+    );
+  } else {
+    const detail = await ghApiJson<GithubRuleset>(
+      "GET",
+      `repos/${repo}/rulesets/${existing.id}`,
+    );
+    if (rulesetProvidesMergeGating(detail)) {
+      instance.log(
+        `✅ ruleset '${MERGE_GATING_RULESET_NAME}' already in place on ${branch}`,
+      );
+    } else {
+      await ghApiJson(
+        "PUT",
+        `repos/${repo}/rulesets/${existing.id}`,
+        desiredMergeGatingRuleset(),
+      );
+      instance.log(
+        `✅ ruleset '${MERGE_GATING_RULESET_NAME}' restored — '${AGGREGATE_CHECK_JOB_NAME}' required, release-job bypass in place`,
+      );
+    }
+  }
+
+  await migrateAwayFromClassicProtection(instance, repo, branch);
+};
+
+/**
+ * removes the aggregate check from a classic branch protection rule
+ * set up by earlier catladder versions — with the check now required
+ * via the ruleset, the classic one would still reject the release
+ * job's push. Everything else in the rule is preserved; the whole rule
+ * is deleted when the check was all it carried.
+ */
+const migrateAwayFromClassicProtection = async (
+  instance: IO,
+  repo: string,
+  branch: string,
+) => {
   const protection = await ghApiJson<any>(
     "GET",
     `repos/${repo}/branches/${branch}/protection`,
-  ).catch(() => null); // 404: branch not protected yet
-
-  const existingChecks: Array<{ context: string; app_id?: number }> =
+  ).catch(() => null); // 404: branch not protected
+  const checks: Array<{ context: string; app_id?: number }> =
     protection?.required_status_checks?.checks ?? [];
-  if (existingChecks.some((c) => c.context === AGGREGATE_CHECK_JOB_NAME)) {
+  if (!checks.some((c) => c.context === AGGREGATE_CHECK_JOB_NAME)) {
+    return;
+  }
+  const remaining = checks.filter(
+    (c) => c.context !== AGGREGATE_CHECK_JOB_NAME,
+  );
+  const carriesAnythingElse =
+    remaining.length > 0 ||
+    protection?.enforce_admins?.enabled ||
+    protection?.required_pull_request_reviews ||
+    protection?.restrictions ||
+    protection?.required_linear_history?.enabled ||
+    protection?.required_conversation_resolution?.enabled ||
+    protection?.required_signatures?.enabled ||
+    protection?.lock_branch?.enabled ||
+    protection?.allow_force_pushes?.enabled ||
+    protection?.allow_deletions?.enabled;
+  if (!carriesAnythingElse) {
+    await ghApiJson("DELETE", `repos/${repo}/branches/${branch}/protection`);
     instance.log(
-      `✅ '${AGGREGATE_CHECK_JOB_NAME}' already required on ${branch}`,
+      `✅ classic branch protection on ${branch} removed — '${AGGREGATE_CHECK_JOB_NAME}' was all it carried, and it is now required via the ruleset`,
     );
     return;
   }
-
-  // merge into whatever protection exists; PUT replaces the whole rule,
-  // so every preserved setting must be carried over explicitly
+  // PUT replaces the whole rule, so every preserved setting must be
+  // carried over explicitly
   await ghApiJson("PUT", `repos/${repo}/branches/${branch}/protection`, {
-    required_status_checks: {
-      strict: protection?.required_status_checks?.strict ?? false,
-      checks: [
-        ...existingChecks.map(({ context, app_id }) => ({
-          context,
-          ...(app_id !== undefined ? { app_id } : {}),
-        })),
-        { context: AGGREGATE_CHECK_JOB_NAME },
-      ],
-    },
+    required_status_checks:
+      remaining.length > 0
+        ? {
+            strict: protection?.required_status_checks?.strict ?? false,
+            checks: remaining.map(({ context, app_id }) => ({
+              context,
+              ...(app_id !== undefined ? { app_id } : {}),
+            })),
+          }
+        : null,
     enforce_admins: protection?.enforce_admins?.enabled ?? false,
     required_pull_request_reviews: protection?.required_pull_request_reviews
       ? {
@@ -108,10 +182,15 @@ export const setupGithub = async (instance: IO, config: Config) => {
           apps: protection.restrictions.apps.map((a: any) => a.slug),
         }
       : null,
+    required_linear_history:
+      protection?.required_linear_history?.enabled ?? false,
+    required_conversation_resolution:
+      protection?.required_conversation_resolution?.enabled ?? false,
+    lock_branch: protection?.lock_branch?.enabled ?? false,
     allow_force_pushes: protection?.allow_force_pushes?.enabled ?? false,
     allow_deletions: protection?.allow_deletions?.enabled ?? false,
   });
   instance.log(
-    `✅ branch protection on ${branch}: '${AGGREGATE_CHECK_JOB_NAME}' required (merges now wait for the pipeline)`,
+    `✅ '${AGGREGATE_CHECK_JOB_NAME}' removed from classic branch protection on ${branch} — now required via the ruleset; the rest of the rule is preserved`,
   );
 };

package/src/release/changesetsReleaseJob.ts

@@ -84,7 +84,25 @@ const pushCommitAndTag = async (tag: string) => {
   // rederived an existing version)
   if (process.env.GITHUB_ACTIONS === "true") {
     const branch = requireEnv("GITHUB_REF_NAME");
-    await git("push", "--atomic", "origin", `HEAD:refs/heads/${branch}`, tag);
+    try {
+      await git("push", "--atomic", "origin", `HEAD:refs/heads/${branch}`, tag);
+    } catch (e) {
+      // GH006: classic branch protection with a required status check
+      // rejects the fresh release commit (it cannot have a passing
+      // check yet) — merge gating must live in a ruleset with a bypass
+      // for the actions app, which `project setup` configures
+      if (/GH006|protected branch/i.test(`${e?.message ?? e}`)) {
+        throw new Error(
+          `pushing the release to '${branch}' was rejected by its branch protection:\n` +
+            `${e.message}\n` +
+            `The release job pushes the release commit and tag with the workflow token. ` +
+            `Required status checks on '${branch}' must live in a repository ruleset with a ` +
+            `bypass for GitHub Actions — classic branch protection cannot allow that push. ` +
+            `Run \`catladder project setup\` to migrate the merge gating, then rerun this job.`,
+        );
+      }
+      throw e;
+    }
     return;
   }
   const token = requireEnv("GL_TOKEN");

package/src/utils/github.ts

@@ -170,7 +170,7 @@ export const ensureGithubEnvironment = async (
 
 /** runs `gh api` with an optional JSON body and returns the parsed response */
 export const ghApiJson = async <T = any>(
-  method: "GET" | "PATCH" | "PUT",
+  method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE",
   path: string,
   body?: unknown,
 ): Promise<T> => {