@catladder/cli 5.1.2 → 5.2.0

package/package.json

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

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

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { findReleaseJobImageDrift } from "../doctor/checkGithubReleaseWorkflow";
+
+const CURRENT = "ghcr.io/fiulag/nautilus/catladder-semantic-release:abc123";
+const OLD = "ghcr.io/fiulag/nautilus/catladder-semantic-release:0ld";
+
+const workflow = (image: string) => ({
+  name: "🚀 catladder create release",
+  on: { workflow_dispatch: {} },
+  jobs: {
+    "create-release": {
+      name: "create release",
+      "runs-on": "ubuntu-latest",
+      container: { image },
+      steps: [{ run: "semanticRelease" }],
+    },
+  },
+});
+
+const committedYaml = (image: string) => `
+name: 🚀 catladder create release
+jobs:
+  create-release:
+    name: create release
+    container:
+      image: ${image}
+`;
+
+const generated = {
+  "catladder-create-release.yml": workflow(CURRENT),
+  "catladder-review.yml": {
+    name: "🛠️ catladder review",
+    on: {},
+    jobs: { lint: { name: "lint", "runs-on": "ubuntu-latest", steps: [] } },
+  },
+} as any;
+
+describe("findReleaseJobImageDrift", () => {
+  it("is quiet when the committed release job runs the generated image", () => {
+    expect(
+      findReleaseJobImageDrift(generated, {
+        "catladder-create-release.yml": committedYaml(CURRENT),
+      }),
+    ).toEqual([]);
+  });
+
+  it("reports a committed workflow generated by an older catladder (older image tag)", () => {
+    expect(
+      findReleaseJobImageDrift(generated, {
+        "catladder-create-release.yml": committedYaml(OLD),
+      }),
+    ).toEqual([
+      {
+        file: "catladder-create-release.yml",
+        expected: CURRENT,
+        committed: OLD,
+      },
+    ]);
+  });
+
+  it("reports a missing or unparsable committed workflow", () => {
+    expect(
+      findReleaseJobImageDrift(generated, {
+        "catladder-create-release.yml": null,
+      }),
+    ).toEqual([
+      {
+        file: "catladder-create-release.yml",
+        expected: CURRENT,
+        committed: null,
+      },
+    ]);
+    expect(
+      findReleaseJobImageDrift(generated, {
+        "catladder-create-release.yml": "jobs: [not: a: workflow",
+      }),
+    ).toEqual([
+      {
+        file: "catladder-create-release.yml",
+        expected: CURRENT,
+        committed: null,
+      },
+    ]);
+  });
+
+  it("only looks at workflows carrying a release job", () => {
+    expect(findReleaseJobImageDrift(generated, {})).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,125 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import type { Config } from "@catladder/pipeline";
+import {
+  getEnabledPipelineTypes,
+  GithubBackend,
+  JobImagesPlan,
+  resolveGithubRegistryImage,
+} from "@catladder/pipeline";
+import { parse } from "yaml";
+import type { DoctorReport } from "./DoctorReport";
+
+const WORKFLOWS_FOLDER = ".github/workflows";
+
+/** the job name of the release job, see githubReleaseJobs.ts */
+const RELEASE_JOB_NAME = "create release";
+
+type Workflows = Awaited<ReturnType<GithubBackend["createWorkflows"]>>;
+
+export type ReleaseJobImageDrift = {
+  file: string;
+  expected: string;
+  /** null when the committed workflow has no release job (or no file) */
+  committed: string | null;
+};
+
+const releaseJobImage = (workflow: {
+  jobs?: Record<string, { name?: string; container?: unknown }>;
+}): string | null => {
+  const job = Object.values(workflow.jobs ?? {}).find(
+    (job) => job?.name === RELEASE_JOB_NAME,
+  );
+  const container = job?.container;
+  if (typeof container === "string") return container;
+  if (container && typeof container === "object" && "image" in container) {
+    return `${(container as { image: unknown }).image}`;
+  }
+  return null;
+};
+
+/**
+ * compares the release job image of every generated workflow carrying
+ * one against the committed workflow of the same name. The job images
+ * are tagged by a content hash of their definition, so a differing tag
+ * means the committed workflow runs an older release image.
+ */
+export const findReleaseJobImageDrift = (
+  generated: Workflows,
+  committed: Record<string, string | null>,
+): ReleaseJobImageDrift[] =>
+  Object.entries(generated).flatMap(([file, workflow]) => {
+    const expected = releaseJobImage(workflow);
+    if (!expected) return [];
+    const content = committed[file];
+    let committedImage: string | null = null;
+    if (content) {
+      try {
+        committedImage = releaseJobImage(parse(content) ?? {});
+      } catch {
+        committedImage = null;
+      }
+    }
+    return committedImage === expected
+      ? []
+      : [{ file, expected, committed: committedImage }];
+  });
+
+/**
+ * the release job image in the committed workflows must be the one this
+ * catladder version generates. The image tag encodes the image
+ * definition, so an older tag means an older release script — which is
+ * more than cosmetics: the semantic-release image before this check
+ * pushed with the workflow token and ignored the release deploy key,
+ * so every release on a repository with merge gating failed on GH013
+ * while `project setup` and the deploy-key checks reported all green.
+ *
+ * Needs no `gh` login — only the config and the committed files.
+ */
+export const checkGithubReleaseWorkflow = async (
+  report: DoctorReport,
+  config: Config,
+) => {
+  if (!getEnabledPipelineTypes(config).includes("github")) return;
+  report.section("github release workflow");
+
+  let generated: Workflows;
+  try {
+    const images = new JobImagesPlan(
+      "github",
+      config.images,
+      await resolveGithubRegistryImage(config),
+    );
+    generated = await new GithubBackend().createWorkflows(config, images);
+  } catch (e) {
+    report.warn(`could not generate the github workflows (${e.message})`);
+    return;
+  }
+
+  const files = Object.keys(generated).filter((file) =>
+    releaseJobImage(generated[file]),
+  );
+  const committed: Record<string, string | null> = {};
+  for (const file of files) {
+    committed[file] = await readFile(
+      join(WORKFLOWS_FOLDER, file),
+      "utf8",
+    ).catch(() => null);
+  }
+
+  const drift = findReleaseJobImageDrift(generated, committed);
+  if (drift.length === 0) {
+    report.ok(
+      `release job image up to date in ${files.length} generated workflow(s)`,
+    );
+    return;
+  }
+  for (const { file, expected, committed } of drift) {
+    report.fail(
+      committed
+        ? `${WORKFLOWS_FOLDER}/${file}: the release job runs ${committed}, this catladder version generates ${expected} — the committed workflow was generated by an older catladder (its release script may push with the workflow token, ignoring the release deploy key)`
+        : `${WORKFLOWS_FOLDER}/${file}: missing or without a '${RELEASE_JOB_NAME}' job (expected image ${expected})`,
+      "run: catenv (and commit the regenerated workflows)",
+    );
+  }
+};

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

@@ -8,6 +8,7 @@ import type { IO } from "../../../../../core/types";
 import { checkCloudRun } from "./checkCloudRun";
 import { checkGithub } from "./checkGithub";
 import { checkGithubImageCasing } from "./checkGithubImageCasing";
+import { checkGithubReleaseWorkflow } from "./checkGithubReleaseWorkflow";
 import { checkGitlab } from "./checkGitlab";
 import { checkStore } from "./checkStore";
 import { DoctorReport } from "./DoctorReport";
@@ -55,6 +56,7 @@ export const doctorProject = async (
   }
   await checkCloudRun(report, contexts);
   await checkGithubImageCasing(report, config);
+  await checkGithubReleaseWorkflow(report, config);
   await checkGithub(report, config);
 
   report.summarize();

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

@@ -32,7 +32,10 @@ export const RELEASE_DEPLOY_KEY_TITLE = "catladder release";
 
 /**
  * actions secret holding the deploy key's private half; the generated
- * release jobs pass it to catci, which pushes over ssh when it is set
+ * release jobs pass it into the job env and both release methods push
+ * over ssh with it when it is set — changesets from catci itself,
+ * semantic-release via the ssh repository url catci prepares for it
+ * (see src/release/githubDeployKey.ts)
  */
 export const RELEASE_DEPLOY_KEY_SECRET = "CATLADDER_RELEASE_KEY";
 

package/src/catci.ts

@@ -24,6 +24,7 @@ import {
   dispatchTaggedReleaseWorkflow,
 } from "./release/changesetsReleaseJob";
 import { changesetCheckJob } from "./release/changesetCheckJob";
+import { githubDeployKeyRemoteJob } from "./release/githubDeployKey";
 import {
   githubQueueCheckJob,
   githubQueuedGuardJob,
@@ -58,6 +59,13 @@ usage:
       github only: dispatches the generated taggedRelease workflow for
       the tag (tags pushed with the job token don't trigger it)
 
+  catci release github-deploy-key-remote
+      github only, semantic-release path: configures the checkout to
+      push over ssh with the release deploy key (CATLADDER_RELEASE_KEY,
+      the only actor that bypasses the merge-gating ruleset), verifies
+      the key reaches the repository and prints the ssh url for
+      semantic-release's --repository-url
+
   catci release github-queue-check
       github only, first step of the manual create-release task:
       releases right away when the main workflow run for HEAD is green
@@ -175,6 +183,13 @@ const main = async () => {
   ) {
     return dispatchTaggedReleaseWorkflow(args[0]);
   }
+  if (
+    group === "release" &&
+    command === "github-deploy-key-remote" &&
+    args.length === 0
+  ) {
+    return githubDeployKeyRemoteJob();
+  }
   if (
     group === "release" &&
     command === "github-queue-check" &&

package/src/release/__tests__/githubDeployKey.test.ts

@@ -0,0 +1,148 @@
+import { readFile, stat } from "fs/promises";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  configureDeployKeyRemote,
+  deployKeyRemoteUrl,
+  deployKeySshCommand,
+  githubDeployKeyRemoteJob,
+  pushWithDeployKey,
+  RELEASE_DEPLOY_KEY_ENV,
+  writeDeployKeyFile,
+} from "../githubDeployKey";
+import { git, gitWithEnv } from "../releaseGit";
+
+vi.mock("../releaseGit", () => ({
+  git: vi.fn(async () => ""),
+  gitWithEnv: vi.fn(async () => ""),
+}));
+
+const KEY =
+  "-----BEGIN OPENSSH PRIVATE KEY-----\nabc\n-----END OPENSSH PRIVATE KEY-----";
+
+describe("github release deploy key", () => {
+  const env = { ...process.env };
+  beforeEach(() => {
+    process.env.GITHUB_REPOSITORY = "FiulAG/nautilus";
+    delete process.env.GITHUB_SERVER_URL;
+    delete process.env[RELEASE_DEPLOY_KEY_ENV];
+    vi.mocked(git).mockClear();
+    vi.mocked(gitWithEnv).mockClear();
+    vi.mocked(git).mockResolvedValue("");
+  });
+  afterEach(() => {
+    process.env = { ...env };
+    vi.restoreAllMocks();
+  });
+
+  describe("deployKeyRemoteUrl", () => {
+    it("is the ssh url of the repository on github.com", () => {
+      expect(deployKeyRemoteUrl()).toBe("git@github.com:FiulAG/nautilus.git");
+    });
+
+    it("follows GITHUB_SERVER_URL on an enterprise host", () => {
+      process.env.GITHUB_SERVER_URL = "https://github.example.com";
+      expect(deployKeyRemoteUrl()).toBe(
+        "git@github.example.com:FiulAG/nautilus.git",
+      );
+    });
+
+    it("fails without the repository", () => {
+      delete process.env.GITHUB_REPOSITORY;
+      expect(() => deployKeyRemoteUrl()).toThrow(
+        "GITHUB_REPOSITORY is not set",
+      );
+    });
+  });
+
+  describe("writeDeployKeyFile", () => {
+    it("writes the key with a trailing newline, readable by the owner only", async () => {
+      const { keyFile } = await writeDeployKeyFile(KEY);
+      expect(await readFile(keyFile, "utf8")).toBe(`${KEY}\n`);
+      expect((await stat(keyFile)).mode & 0o777).toBe(0o600);
+    });
+
+    it("does not add a second newline", async () => {
+      const { keyFile } = await writeDeployKeyFile(`${KEY}\n`);
+      expect(await readFile(keyFile, "utf8")).toBe(`${KEY}\n`);
+    });
+  });
+
+  it("the ssh command uses exactly the deploy key", () => {
+    expect(deployKeySshCommand("/tmp/k/id_ed25519")).toBe(
+      "ssh -i /tmp/k/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new",
+    );
+  });
+
+  describe("pushWithDeployKey (changesets path)", () => {
+    it("pushes the refs atomically to the ssh url with the key", async () => {
+      await pushWithDeployKey(KEY, ["HEAD:refs/heads/main", "v1.2.3"]);
+      expect(gitWithEnv).toHaveBeenCalledTimes(1);
+      const [env, ...args] = vi.mocked(gitWithEnv).mock.calls[0];
+      expect(env.GIT_SSH_COMMAND).toMatch(
+        /^ssh -i \S+id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new$/,
+      );
+      expect(args).toEqual([
+        "push",
+        "--atomic",
+        "git@github.com:FiulAG/nautilus.git",
+        "HEAD:refs/heads/main",
+        "v1.2.3",
+      ]);
+    });
+  });
+
+  describe("configureDeployKeyRemote (semantic-release path)", () => {
+    it("points git's ssh at the key, verifies the key reaches the repo and returns the ssh url", async () => {
+      const remote = await configureDeployKeyRemote(KEY);
+      expect(remote).toBe("git@github.com:FiulAG/nautilus.git");
+      const calls = vi.mocked(git).mock.calls;
+      expect(calls[0].slice(0, 2)).toEqual(["config", "core.sshCommand"]);
+      expect(calls[0][2]).toMatch(
+        /^ssh -i \S+id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new$/,
+      );
+      expect(calls[1]).toEqual([
+        "ls-remote",
+        "--exit-code",
+        "git@github.com:FiulAG/nautilus.git",
+        "HEAD",
+      ]);
+    });
+
+    it("fails with the remediation when the key does not reach the repository", async () => {
+      vi.mocked(git).mockImplementation(async (...args) => {
+        if (args[0] === "ls-remote") {
+          throw new Error("git@github.com: Permission denied (publickey).");
+        }
+        return "";
+      });
+      await expect(configureDeployKeyRemote(KEY)).rejects.toThrow(
+        /cannot reach git@github\.com:FiulAG\/nautilus\.git: .*Permission denied[\s\S]*CATLADDER_RELEASE_KEY secret does not match the 'catladder release' deploy key[\s\S]*catladder project setup/,
+      );
+    });
+  });
+
+  describe("githubDeployKeyRemoteJob (catci release github-deploy-key-remote)", () => {
+    it("prints only the ssh url on stdout, the log on stderr", async () => {
+      process.env[RELEASE_DEPLOY_KEY_ENV] = KEY;
+      const stdout = vi
+        .spyOn(process.stdout, "write")
+        .mockImplementation(() => true);
+      const stderr = vi.spyOn(console, "error").mockImplementation(() => {});
+      await githubDeployKeyRemoteJob();
+      expect(stdout).toHaveBeenCalledTimes(1);
+      expect(stdout).toHaveBeenCalledWith(
+        "git@github.com:FiulAG/nautilus.git\n",
+      );
+      expect(stderr).toHaveBeenCalledWith(
+        expect.stringContaining("over ssh with the release deploy key"),
+      );
+    });
+
+    it("refuses to run without the secret", async () => {
+      await expect(githubDeployKeyRemoteJob()).rejects.toThrow(
+        `${RELEASE_DEPLOY_KEY_ENV} is not set`,
+      );
+      expect(git).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/release/changesetsReleaseJob.ts

@@ -6,8 +6,7 @@
  * pushes — the pushed tag triggers the taggedRelease pipeline.
  */
 import { existsSync } from "fs";
-import { mkdtemp, readFile, readdir, rm, writeFile } from "fs/promises";
-import { tmpdir } from "os";
+import { readFile, readdir, rm, writeFile } from "fs/promises";
 import { join } from "path";
 import type { Changeset } from "./changesets";
 import {
@@ -18,11 +17,11 @@ import {
   renderChangelogEntries,
 } from "./changesets";
 import {
-  ensureReleaseHistory,
-  getLastReleaseTag,
-  git,
-  gitWithEnv,
-} from "./releaseGit";
+  getReleaseDeployKey,
+  pushWithDeployKey,
+  RELEASE_DEPLOY_KEY_ENV,
+} from "./githubDeployKey";
+import { ensureReleaseHistory, getLastReleaseTag, git } from "./releaseGit";
 import { createReleaseEntry } from "./releaseEntry";
 import { appendStepSummary } from "./stepSummary";
 
@@ -82,12 +81,11 @@ const requireEnv = (name: string): string => {
  * - gitlab: CI checkouts have a read-only origin, so push via an
  *   authenticated url with GL_TOKEN (the same project access token
  *   semantic-release uses)
- * - github: over ssh with the release deploy key
- *   (CATLADDER_RELEASE_KEY, provisioned by `project setup`) — merge
- *   gating requires the `catladder ✅` check on the default branch,
- *   and only a deploy key can bypass that (github deliberately never
- *   lets the workflow token bypass rulesets). Without the secret the
- *   push falls back to origin, which works on repos without gating.
+ * - github: over ssh with the release deploy key (see
+ *   ./githubDeployKey) — merge gating requires the `catladder ✅` check
+ *   on the default branch, and only a deploy key can bypass that.
+ *   Without the secret the push falls back to origin (the workflow
+ *   token), which works on repos without gating.
  */
 const pushCommitAndTag = async (tag: string) => {
   // --atomic: all refs or none — a rejected tag must not leave the
@@ -96,7 +94,7 @@ const pushCommitAndTag = async (tag: string) => {
   if (process.env.GITHUB_ACTIONS === "true") {
     const branch = requireEnv("GITHUB_REF_NAME");
     const refs = [`HEAD:refs/heads/${branch}`, tag];
-    const deployKey = process.env.CATLADDER_RELEASE_KEY;
+    const deployKey = getReleaseDeployKey();
     if (deployKey) {
       await pushWithDeployKey(deployKey, refs);
       return;
@@ -104,16 +102,21 @@ const pushCommitAndTag = async (tag: string) => {
     try {
       await git("push", "--atomic", "origin", ...refs);
     } catch (e) {
-      // GH006: a required status check rejects the fresh release
-      // commit (it cannot have a passing check yet) — the push needs
-      // the release deploy key, which `project setup` provisions
-      if (/GH006|protected branch/i.test(`${e?.message ?? e}`)) {
+      // GH006 (classic protection) / GH013 (ruleset): a required status
+      // check rejects the fresh release commit (it cannot have a
+      // passing check yet) — the push needs the release deploy key,
+      // which `project setup` provisions
+      if (
+        /GH006|GH013|protected branch|rule violations/i.test(
+          `${e?.message ?? e}`,
+        )
+      ) {
         throw new Error(
           `pushing the release to '${branch}' was rejected by its branch protection:\n` +
             `${e.message}\n` +
             `The workflow token cannot bypass a required status check on '${branch}'. ` +
             `Run \`catladder project setup\` to provision the release deploy key ` +
-            `(${RELEASE_KEY_ENV} secret + ruleset bypass), then rerun this job.`,
+            `(${RELEASE_DEPLOY_KEY_ENV} secret + ruleset bypass), then rerun this job.`,
         );
       }
       throw e;
@@ -128,41 +131,6 @@ const pushCommitAndTag = async (tag: string) => {
   await git("push", "--atomic", remote, `HEAD:refs/heads/${branch}`, tag);
 };
 
-const RELEASE_KEY_ENV = "CATLADDER_RELEASE_KEY";
-
-/**
- * pushes over ssh with the release deploy key — the only actor that
- * can bypass the merge-gating ruleset on the default branch
- */
-const pushWithDeployKey = async (privateKey: string, refs: string[]) => {
-  const serverUrl = process.env.GITHUB_SERVER_URL ?? "https://github.com";
-  const host = new URL(serverUrl).host;
-  const repository = requireEnv("GITHUB_REPOSITORY");
-  const dir = await mkdtemp(join(tmpdir(), "release-key-"));
-  try {
-    const keyFile = join(dir, "id_ed25519");
-    // a key file without a trailing newline is rejected by openssh
-    await writeFile(
-      keyFile,
-      privateKey.endsWith("\n") ? privateKey : `${privateKey}\n`,
-      {
-        mode: 0o600,
-      },
-    );
-    await gitWithEnv(
-      {
-        GIT_SSH_COMMAND: `ssh -i ${keyFile} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`,
-      },
-      "push",
-      "--atomic",
-      `git@${host}:${repository}.git`,
-      ...refs,
-    );
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-};
-
 /**
  * tags pushed with the default GITHUB_TOKEN do not trigger `on: push:
  * tags` workflows (github's recursion guard), so the taggedRelease
@@ -267,9 +235,12 @@ export const changesetsReleaseJob = async () => {
   // [skip ci] on github only: deploy-key pushes trigger workflows
   // (unlike GITHUB_TOKEN pushes), and neither the release commit nor
   // the tag needs a push-triggered run — the taggedRelease workflow is
-  // dispatched explicitly below, [skip ci] keeps it the only run. On
-  // gitlab the tag pipeline MUST fire natively, so no marker there
-  // (release-commit branch pipelines are already filtered by rules).
+  // dispatched explicitly below, [skip ci] keeps it the only run
+  // (verified on catladder's own releases: one run per tag, all
+  // workflow_dispatch). The semantic-release runner script does the
+  // same. On gitlab the tag pipeline MUST fire natively, so no marker
+  // there (release-commit branch pipelines are already filtered by
+  // rules).
   const onGithub = process.env.GITHUB_ACTIONS === "true";
   const subject = `chore(release): ${version}${onGithub ? " [skip ci]" : ""}`;
   await git("commit", "-m", `${subject}\n\n${entries}`);