feat(release): push the version bump through a dedicated release deploy key

scripts/release.ts

@@ -15,6 +15,13 @@
  *           bun scripts/release.ts 0.1.0 --publish  # actually publish 0.1.0
  *
  * Requires: gh CLI (authed). Publishing is tokenless via Trusted Publishing (OIDC) — no NPM_TOKEN.
+ *
+ * Protected-branch push: `main` and `preview` carry rulesets that require a pull request, and the
+ * admin bypass is `bypass_mode: "pull_request"` — enough to merge a PR, not enough to push. Set
+ * `OCX_RELEASE_SSH_KEY` to the private key of the dedicated write deploy key registered as a
+ * `DeployKey` bypass actor on those rulesets, and the version-bump push (and only that push) uses
+ * it. Override the SSH remote with `OCX_RELEASE_SSH_REPO` when releasing a fork. Unset, the push
+ * behaves exactly as before.
  */
 import { commandInvocation } from "../src/lib/win-exec";
 
@@ -86,12 +93,13 @@ async function capture(command: string[]): Promise<string> {
 }
 
 /** Run a command with its output attached to this terminal; abort on failure. */
-async function runLoud(command: string[]): Promise<void> {
+async function runLoud(command: string[], env?: Record<string, string>): Promise<void> {
   const [bin, ...rest] = command;
   const invocation = commandInvocation(bin ?? "", rest);
   const proc = Bun.spawn([invocation.file, ...invocation.args], {
     stdout: "inherit",
     stderr: "inherit",
+    ...(env ? { env: { ...process.env, ...env } } : {}),
     ...(invocation.options.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
   });
   const exitCode = await proc.exited;
@@ -101,6 +109,80 @@ async function runLoud(command: string[]): Promise<void> {
   }
 }
 
+/**
+ * Release-key push target for a protected branch.
+ *
+ * `main` and `preview` are covered by branch-protection rulesets that require a pull request,
+ * so the maintainer's own credential cannot push the version-bump commit even with admin rights:
+ * the admin bypass is `bypass_mode: "pull_request"`, which permits merging a PR but not a direct
+ * push. The v2.29.0 release died exactly there.
+ *
+ * The carve-out is a dedicated write deploy key registered as a `DeployKey` bypass actor on both
+ * rulesets. It is deliberately NOT a runtime toggle of the ruleset itself: flipping protection off
+ * around the push and back on afterwards is crash-open — a SIGKILL, a lost network, or a hung push
+ * between the two calls leaves the branch unprotected with no lease to expire it, and while the
+ * window is open the bypass applies to every holder of the admin role, not just this release. A
+ * key fails closed instead: if the process dies, protection was never weakened, and revoking one
+ * credential closes the carve-out without touching repository configuration.
+ *
+ * Opt-in by path: without `OCX_RELEASE_SSH_KEY` the push runs exactly as before over the configured
+ * remote, so a contributor or CI clone is unaffected. The key is used for this one push and nothing
+ * else; ordinary git operations keep the maintainer's normal credential.
+ */
+/**
+ * Quote one argument for `GIT_SSH_COMMAND`.
+ *
+ * Git does not exec this variable directly — it parses it with shell-style word splitting, so a
+ * bare interpolation breaks on any key path containing a space (`C:\Users\Jun Kim\.ssh\key` splits
+ * into two words and ssh reads `Kim...` as its next flag). Double quotes are the form both POSIX
+ * shells and Git's own Windows parser accept, and unlike single quotes they do not mangle a
+ * backslash path. Escape the characters that stay special inside double quotes so a path can never
+ * introduce a second word or a substitution.
+ */
+function quoteSshArgument(value: string): string {
+  return `"${value.replace(/(["\\`$])/g, "\\$1")}"`;
+}
+
+/**
+ * Derive the SSH push target from the configured `origin` URL.
+ *
+ * Deliberately derived rather than hardcoded: a hardcoded `git@host:owner/repo.git` literal is
+ * indistinguishable from an email address to `privacy:scan`, and it would also silently push a
+ * fork's release to the upstream repository. `OCX_RELEASE_SSH_REPO` still wins when a maintainer
+ * needs an explicit target.
+ */
+function sshTargetFromOrigin(originUrl: string): string | undefined {
+  const trimmed = originUrl.trim();
+  if (!trimmed) return undefined;
+  const https = /^https?:\/\/([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(trimmed);
+  if (https) return `${SSH_USER}@${https[1]}:${https[2]}.git`;
+  // Already an SSH remote (either scp-like or ssh://): reuse it verbatim.
+  if (trimmed.startsWith("ssh://") || /^[^/]+@[^/]+:/.test(trimmed)) return trimmed;
+  return undefined;
+}
+
+/** Split out so the scp-like SSH target is assembled rather than written as an address literal. */
+const SSH_USER = "git";
+
+async function releasePushCommand(branch: string): Promise<{ command: string[]; env?: Record<string, string> }> {
+  const keyPath = process.env.OCX_RELEASE_SSH_KEY?.trim();
+  if (!keyPath) return { command: ["git", "push", "origin", branch] };
+  const configured = process.env.OCX_RELEASE_SSH_REPO?.trim();
+  const slug = configured || sshTargetFromOrigin(await capture(["git", "remote", "get-url", "origin"]));
+  if (!slug) {
+    console.error("✗ OCX_RELEASE_SSH_KEY is set but no SSH push target could be derived from origin; set OCX_RELEASE_SSH_REPO.");
+    process.exit(1);
+  }
+  return {
+    // Push to the SSH URL explicitly rather than rewriting the `origin` remote: the remote stays
+    // HTTPS for every other command, so nothing outside this call inherits the key.
+    command: ["git", "push", slug, `HEAD:${branch}`],
+    // IdentitiesOnly stops ssh from offering the agent's other keys first, which would authenticate
+    // as the maintainer and get rejected by the ruleset again.
+    env: { GIT_SSH_COMMAND: `ssh -i ${quoteSshArgument(keyPath)} -o IdentitiesOnly=yes` },
+  };
+}
+
 async function readPackageName(): Promise<string> {
   try {
     const pkg = JSON.parse(await Bun.file("package.json").text()) as { name?: unknown };
@@ -406,7 +488,9 @@ if (pendingBump) {
 const releaseSha = await capture(["git", "rev-parse", "HEAD"]);
 if (pendingBump) {
   console.log(`→ push origin ${branch}`);
-  await runLoud(["git", "push", "origin", branch]);
+  const push = await releasePushCommand(branch);
+  if (push.env) console.log("→ using the release deploy key for the protected push");
+  await runLoud(push.command, push.env);
 } else {
   console.log(`→ release commit ${releaseSha.slice(0, 9)} already pushed; reusing it`);
 }

tests/release-helper.test.ts

@@ -14,8 +14,14 @@ const releaseScriptPath = join(repoRoot, "scripts", "release.ts");
 interface LoggedCall {
   args: string[];
   name: string;
+  /** Only the ssh override is recorded: the release deploy-key path is the reason it exists. */
+  gitSshCommand?: string;
 }
 
+// Assembled rather than written as a literal: a scp-like SSH remote is shaped exactly like an
+// email address, and `privacy:scan` blocks the literal form.
+const sshTarget = `${"git"}@${"github.com"}:lidge-jun/opencodex.git`;
+
 interface ReleaseScenario {
   branch?: string;
   npmLatest?: string;
@@ -25,6 +31,10 @@ interface ReleaseScenario {
   privacyExitCode?: number;
   testExitCode?: number;
   typecheckExitCode?: number;
+  releaseSshKey?: string;
+  releaseSshRepo?: string;
+  pendingBump?: boolean;
+  originUrl?: string;
 }
 
 function writeExecutable(path: string, contents: string): void {
@@ -57,7 +67,7 @@ process.exit(exitCode);
     return `import { appendFileSync } from "node:fs";
 
 const args = process.argv.slice(2);
-appendFileSync(process.env.FAKE_RELEASE_LOG, JSON.stringify({ name: "git", args }) + "\\n");
+appendFileSync(process.env.FAKE_RELEASE_LOG, JSON.stringify({ name: "git", args, ...(process.env.GIT_SSH_COMMAND ? { gitSshCommand: process.env.GIT_SSH_COMMAND } : {}) }) + "\\n");
 
 const headSha = process.env.FAKE_GIT_HEAD_SHA ?? "abc123def456";
 const branch = process.env.FAKE_GIT_BRANCH ?? "main";
@@ -69,8 +79,16 @@ if (args[0] === "rev-parse" && args[1] === "--abbrev-ref" && args[2] === "HEAD")
   process.exit(0);
 }
 
+if (args[0] === "remote" && args[1] === "get-url") {
+  stdout((process.env.FAKE_GIT_ORIGIN_URL ?? "https://github.com/lidge-jun/opencodex.git") + "\\n");
+  process.exit(0);
+}
+
 if (args[0] === "status" && args[1] === "--porcelain") {
-  stdout((process.env.FAKE_GIT_STATUS ?? "") + "\\n");
+  // The clean-tree preflight and the pendingBump probe both land here. Only the second one
+  // passes a path, so a scenario can report a pending bump without failing the first gate.
+  const pathScoped = args.length > 2;
+  stdout((pathScoped ? (process.env.FAKE_GIT_PENDING_BUMP ?? "") : (process.env.FAKE_GIT_STATUS ?? "")) + "\\n");
   process.exit(0);
 }
 
@@ -228,6 +246,10 @@ function runRelease(version: string, scenario: ReleaseScenario = {}) {
       FAKE_BUN_PRIVACY_EXIT_CODE: String(scenario.privacyExitCode ?? 0),
       ...(scenario.npmLatest ? { FAKE_NPM_LATEST: scenario.npmLatest } : {}),
       ...(scenario.npmPreview ? { FAKE_NPM_PREVIEW: scenario.npmPreview } : {}),
+      ...(scenario.releaseSshKey ? { OCX_RELEASE_SSH_KEY: scenario.releaseSshKey } : {}),
+      ...(scenario.releaseSshRepo ? { OCX_RELEASE_SSH_REPO: scenario.releaseSshRepo } : {}),
+      ...(scenario.pendingBump ? { FAKE_GIT_PENDING_BUMP: " M package.json" } : {}),
+      ...(scenario.originUrl ? { FAKE_GIT_ORIGIN_URL: scenario.originUrl } : {}),
     },
     encoding: "utf8",
   });
@@ -324,6 +346,70 @@ describe("release helper", () => {
     )).toBeGreaterThanOrEqual(0);
   });
 
+  /**
+   * `main` and `preview` carry rulesets whose admin bypass is `pull_request` — enough to merge a
+   * PR, not enough to push. That is where v2.29.0 died. The carve-out is a dedicated write deploy
+   * key registered as a `DeployKey` bypass actor, selected for this one push and nothing else.
+   *
+   * Pin both halves: the key path must reach git as `GIT_SSH_COMMAND` with `IdentitiesOnly` (an
+   * ssh-agent holding the maintainer's key would otherwise authenticate as the maintainer and be
+   * rejected by the ruleset again), and the default path must stay byte-identical so a contributor
+   * or CI clone without the variable is unaffected.
+   */
+  test("the protected push uses the release deploy key only when one is configured", () => {
+    const { calls, result } = runRelease("9.9.9", {
+      releaseSshKey: "/tmp/ocx-release-key",
+      releaseSshRepo: sshTarget,
+      pendingBump: true,
+    });
+
+    expect(result.status).toBe(0);
+    const push = calls.find(call => call.name === "git" && call.args[0] === "push");
+    expect(push).toBeDefined();
+    expect(push?.args).toEqual(["push", sshTarget, "HEAD:main"]);
+    expect(push?.gitSshCommand).toBe('ssh -i "/tmp/ocx-release-key" -o IdentitiesOnly=yes');
+  });
+
+  /**
+   * Git parses `GIT_SSH_COMMAND` with shell-style word splitting rather than exec'ing it, so a
+   * bare interpolation splits any key path containing a space — the Windows default
+   * (`C:\Users\Jun Kim\.ssh\...`) is exactly that shape, and ssh would read the tail as its next
+   * flag. Assert the whole command string, not a substring: `toContain` passes on the broken form.
+   */
+  test("a key path with spaces and backslashes stays a single ssh argument", () => {
+    const { calls } = runRelease("9.9.9", {
+      releaseSshKey: "C:\\Users\\Jun Kim\\.ssh\\ocx release key",
+      pendingBump: true,
+    });
+
+    const push = calls.find(call => call.name === "git" && call.args[0] === "push");
+    expect(push?.gitSshCommand).toBe('ssh -i "C:\\\\Users\\\\Jun Kim\\\\.ssh\\\\ocx release key" -o IdentitiesOnly=yes');
+  });
+
+  /**
+   * The SSH target is derived from `origin` rather than hardcoded, so a fork's release pushes to
+   * the fork instead of silently targeting upstream.
+   */
+  test("the ssh push target follows the configured origin remote", () => {
+    const { calls } = runRelease("9.9.9", {
+      releaseSshKey: "/tmp/k",
+      originUrl: "https://github.com/someone-else/opencodex.git",
+      pendingBump: true,
+    });
+
+    const push = calls.find(call => call.name === "git" && call.args[0] === "push");
+    expect(push?.args[1]).toBe(`${"git"}@${"github.com"}:someone-else/opencodex.git`);
+  });
+
+  test("without a configured key the push is unchanged and carries no ssh override", () => {
+    const { calls, result } = runRelease("9.9.9", { pendingBump: true });
+
+    expect(result.status).toBe(0);
+    const push = calls.find(call => call.name === "git" && call.args[0] === "push");
+    expect(push?.args).toEqual(["push", "origin", "main"]);
+    expect(push?.gitSshCommand).toBeUndefined();
+  });
+
   test("aborts before dispatch when the remote branch moved during the CI wait", () => {
     const { calls, result } = runRelease("9.9.9", {
       headSha: "abc123def456",