@intentius/chant-lexicon-github 0.124.46 → 0.124.49

package/src/components/generate-op-pipeline.review.test.ts

@@ -0,0 +1,152 @@
+/**
+ * The split review (#4326): `ScheduledOpSpec.reviewAgent` makes two jobs, a
+ * review job that runs the change's code with no forge write token and a note
+ * job that checks nothing out and posts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import { CHECKOUT_TOKEN_ENV, checkoutScript, FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateGithubOpPipeline } from "./generate-op-pipeline";
+
+interface Step {
+  id?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+  "working-directory"?: string;
+}
+interface Job {
+  needs?: string;
+  if?: string;
+  permissions?: Record<string, string>;
+  env?: Record<string, string>;
+  outputs?: Record<string, string>;
+  steps: Step[];
+}
+interface Doc {
+  permissions?: Record<string, string>;
+  env?: Record<string, string>;
+  jobs: Record<string, Job>;
+}
+
+const SPEC: ScheduledOpSpec = { name: "pr-review", trigger: { kind: "pull_request" }, reviewAgent: true };
+const gen = (spec: Partial<ScheduledOpSpec> = {}, options = {}) => {
+  const out = generateGithubOpPipeline([{ ...SPEC, ...spec }], options);
+  return { doc: parseYAML(out.files[0]!.yaml) as unknown as Doc, yaml: out.files[0]!.yaml, name: out.files[0]!.name };
+};
+
+describe("the review job", () => {
+  const { doc } = gen();
+  const job = doc.jobs["pr-review"]!;
+
+  test("holds contents: read and nothing that writes to the forge", () => {
+    expect(doc.permissions).toEqual({ contents: "read" });
+    expect(job.permissions).toBeUndefined();
+  });
+
+  test("no step but the checkout's fetches holds a forge token, and none uses actions/checkout", () => {
+    for (const step of job.steps) {
+      const named = Object.keys(step.env ?? {}).filter((n) => (FORGE_TOKEN_VARS as readonly string[]).includes(n));
+      expect(step.uses ?? "").not.toMatch(/^actions\/checkout@/);
+      if (step.run?.trimEnd() === checkoutScript(true).trimEnd()) {
+        expect(named).toEqual([CHECKOUT_TOKEN_ENV]);
+        continue;
+      }
+      expect(named).toEqual([]);
+      expect(JSON.stringify(step.env ?? {}) + JSON.stringify(step.with ?? {})).not.toMatch(/secrets\.|github\.token/);
+    }
+    expect(job.env ?? {}).toEqual({});
+    expect(doc.env ?? {}).toEqual({});
+  });
+
+  test("the checkout carries the base branch's history for the diff", () => {
+    expect(job.steps[0]!.run!.trimEnd()).toBe(checkoutScript(true).trimEnd());
+    expect(job.steps[0]!.run).toContain("+refs/heads/*:refs/remotes/origin/*");
+  });
+
+  test("the Op's step starts without the token variables, names the handoff directory, and hands the review on as the job's outputs", () => {
+    const run = job.steps.at(-1)!;
+    expect(run.id).toBe("chant-review");
+    expect(run.run).toContain("chant run pr-review");
+    expect(run.run).toMatch(/^if .*exec env -u CHANT_FORGE_TOKEN/);
+    expect(run.run).toContain("trap chant_handover EXIT");
+    expect(run.env).toEqual({ CHANT_REVIEW_DIR: ".chant/review" });
+    expect(job.outputs).toEqual({ report_0: "${{ steps.chant-review.outputs.report_0 }}" });
+  });
+
+  test("the Op's step is the last one, so nothing starts beside what the change's code left running", () => {
+    expect(job.steps.at(-1)!.id).toBe("chant-review");
+  });
+});
+
+describe("the note job", () => {
+  const { doc } = gen();
+  const note = doc.jobs["pr-review-note"]!;
+
+  test("needs the review job and runs when it succeeded", () => {
+    expect(note.needs).toBe("pr-review");
+    expect(note.if).toBe("needs.pr-review.result == 'success'");
+  });
+
+  test("checks nothing out and holds the pull-request write scope alone", () => {
+    expect(note.permissions).toEqual({ "pull-requests": "write" });
+    expect(note.steps.some((s) => (s.uses ?? "").startsWith("actions/checkout"))).toBe(false);
+    expect(note.steps.some((s) => (s.run ?? "").includes("git "))).toBe(false);
+  });
+
+  test("takes the review as data and posts it with the job's token, naming the Op itself", () => {
+    expect(note.steps[0]!.run).toContain("toJSON(needs.pr-review.outputs.report_0)");
+    const post = note.steps[1]!;
+    expect(post.env).toEqual({ GITHUB_TOKEN: "${{ github.token }}", CHANT_OP: "pr-review" });
+    expect(post.run).toContain('import { postReviewNote } from "@intentius/chant/op/activities/review-agent";');
+    expect(post.run).toMatch(/npm install .* @intentius\/chant@\d+\.\d+\.\d+/);
+    expect(post.run).not.toContain("${{");
+  });
+
+  test("the job that runs the change's code has no pull-requests scope the note job lacks, and the note job runs none of the change's code", () => {
+    const review = doc.jobs["pr-review"]!;
+    expect(JSON.stringify(review)).not.toContain("pull-requests");
+    expect(note.steps.map((s) => s.run ?? "").join("\n")).not.toContain("chant run");
+  });
+});
+
+describe("what the shape refuses and carries", () => {
+  test("a trigger with no pull request, a finding-mode that writes and a write scope are refused by name", () => {
+    expect(() => gen({ trigger: { kind: "push" } })).toThrow(/pr-review.*"push"/);
+    expect(() => gen({ findingMode: "comment" })).toThrow(/findingMode "comment".*must be "report"/);
+    expect(() => gen({ permissions: { "pull-requests": "write" } })).toThrow(/pull-requests: write/);
+    expect(() => gen({ permissions: { "id-token": "write" } })).not.toThrow();
+  });
+
+  test("setup steps, per-Op variables, beforeScript and extraScript land in the review job", () => {
+    const { doc } = gen(
+      { setup: [{ uses: "aws-actions/configure-aws-credentials@" + "a".repeat(40), with: { "role-to-assume": "arn:aws:iam::1:role/plan" } }], variables: { AWS_REGION: "eu-west-1" }, permissions: { "id-token": "write" } },
+      { beforeScript: ["npm ci"], extraScript: ["echo done"] },
+    );
+    const job = doc.jobs["pr-review"]!;
+    expect(job.env).toEqual({ AWS_REGION: "eu-west-1" });
+    expect(job.steps.some((s) => (s.uses ?? "").startsWith("aws-actions/configure-aws-credentials"))).toBe(true);
+    expect(job.steps.some((s) => (s.run ?? "").includes("\nnpm ci"))).toBe(true);
+    expect(job.steps.at(-1)!.run).toContain("echo done");
+    expect(doc.permissions).toEqual({ contents: "read", "id-token": "write" });
+  });
+
+  test("a member's directory scopes the review job, and the checkout still runs at the repository root", () => {
+    const { doc, name } = gen({}, { member: { name: "network", dir: "infra/network", file: "network.yml" } });
+    expect(name).toBe("network-pr-review.yml");
+    const job = doc.jobs["pr-review"] as Job & { defaults?: { run?: { "working-directory"?: string } } };
+    expect(job.defaults?.run?.["working-directory"]).toBe("infra/network");
+    expect(job.steps[0]!["working-directory"]).toBe(".");
+    expect((doc.jobs["pr-review-note"] as { defaults?: unknown }).defaults).toBeUndefined();
+  });
+
+  test("an Op without reviewAgent keeps its one job and its token", () => {
+    const out = generateGithubOpPipeline([{ name: "plain", trigger: { kind: "pull_request" } }]);
+    const doc = parseYAML(out.files[0]!.yaml) as unknown as Doc;
+    expect(Object.keys(doc.jobs)).toEqual(["plain"]);
+    expect(out.files[0]!.yaml).toContain("GITHUB_TOKEN");
+  });
+});

package/src/components/generate-op-pipeline.test.ts

@@ -16,6 +16,7 @@ import { describe, test, expect } from "vitest";
 import { parseYAML } from "@intentius/chant/yaml";
 import { generateGithubOpPipeline } from "./generate-op-pipeline";
 import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { ACTION_PINS, usesRef } from "@intentius/chant/action-pins";
 
 interface ParsedStep {
   name?: string;
@@ -73,7 +74,7 @@ describe("generateGithubOpPipeline: one file per scheduled Op", () => {
     const job = doc.jobs!["actions-audit"];
 
     expect(job["runs-on"]).toBe("ubuntu-latest");
-    expect(job.steps[0].uses).toBe("actions/checkout@v7");
+    expect(job.steps[0].uses).toBe(`${usesRef(ACTION_PINS.checkout7)}`);
     const runStep = job.steps.find((s) => typeof s.run === "string")!;
     expect(runStep.run).toBe("chant run actions-audit");
   });
@@ -339,7 +340,7 @@ describe("generateGithubOpPipeline: setup steps and additive permissions (#2242)
     const steps = doc.jobs!["app-apply"].steps;
 
     expect(steps.slice(0, 3).map((s) => s.uses ?? s.run)).toEqual([
-      "actions/checkout@v7",
+      `${usesRef(ACTION_PINS.checkout7)}`,
       "aws-actions/configure-aws-credentials@v6",
       "install terraform",
     ]);
@@ -397,7 +398,7 @@ describe("generateGithubOpPipeline: setup steps and additive permissions (#2242)
     ];
     const steps = parseFile(generateGithubOpPipeline(specs).files[0].yaml).jobs!["app-apply"].steps;
     expect(steps.map((s) => s.uses).filter(Boolean)).toEqual([
-      "actions/checkout@v7",
+      `${usesRef(ACTION_PINS.checkout7)}`,
       "github/codeql-action/upload-sarif@v4",
       "aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83",
     ]);
@@ -639,7 +640,7 @@ describe("generateGithubOpPipeline: a deployment environment on the Op's job (#2
       "    runs-on: ubuntu-latest",
       "    container: node:22",
       "    steps:",
-      "      - uses: actions/checkout@v7",
+      `      - uses: ${usesRef(ACTION_PINS.checkout7)} # ${ACTION_PINS.checkout7.tag}`,
       "      - run: chant run actions-audit",
       "        env:",
       "          GITHUB_TOKEN: '${{ github.token }}'",

package/src/components/generate-op-pipeline.ts

@@ -96,6 +96,7 @@ import type {
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
 import { checkoutStep, concurrency, emitWorkflowYAML, jobTokenEnv, onTrigger, opConcurrencyGroup, runSteps } from "./ci-jobs";
+import { assertReviewSplit, reviewJobs, reviewNoteJobName } from "./review-jobs";
 
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 
@@ -154,6 +155,13 @@ export interface GithubOpPipelineDoc {
    * artifact instead (#2256).
    */
   gatedNoticeDoc?: Record<string, unknown>;
+  /**
+   * The review note job (#4326), when the spec sets `reviewAgent`. Kept out
+   * of {@link jobsDoc} for the reason the gate notice is: a member's
+   * `working-directory` default belongs to the job that runs the Op, and a
+   * dialect transforms this job on its own terms.
+   */
+  reviewNoteDoc?: Record<string, unknown>;
 }
 
 /** One generated file: a suggested name plus its pipeline document, pre-emission. */
@@ -427,7 +435,10 @@ export function buildGithubOpPipelineDocs(
 
     // A live-resolution read (rate limits) always benefits from a token;
     // creating an issue/PR additionally needs `gh` CLI's own token variable.
-    const stepEnv = jobTokenEnv(findingMode !== "report");
+    // A split review (#4326) runs the change's code beside a model: no step of that job holds a forge token.
+    const split = spec.reviewAgent === true;
+    if (split) assertReviewSplit(spec.name, trigger, findingMode, spec.permissions);
+    const stepEnv = split ? {} : jobTokenEnv(findingMode !== "report");
 
     const setup = spec.setup ?? [];
     assertSetupSteps(spec.name, setup);
@@ -450,6 +461,20 @@ export function buildGithubOpPipelineDocs(
     );
     steps.push(...runSteps(extraScript));
 
+    const review = split
+      ? reviewJobs({
+          name: spec.name,
+          jobName,
+          image,
+          invocation,
+          setup: setup.map(setupStepDoc),
+          beforeScript,
+          extraScript,
+          ...(spec.variables ? { variables: spec.variables } : {}),
+          ...(options.member ? { member: options.member } : {}),
+        })
+      : undefined;
+
     const doc: GithubOpPipelineDoc = {
       name: spec.name,
       on: onTrigger(trigger),
@@ -492,6 +517,11 @@ export function buildGithubOpPipelineDocs(
       },
       ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image) } } : {}),
     };
+    // A split review (#4326): the Op's job is the review job, and the note job rides beside it.
+    if (review) {
+      doc.jobsDoc = { [jobName]: { ...review.review, ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) } };
+      doc.reviewNoteDoc = { [reviewNoteJobName(jobName)]: review.note };
+    }
 
     files.push({ name: `${spec.name}.yml`, doc });
   }
@@ -550,8 +580,8 @@ export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
   // The gated-apply notice job rides in `jobs:` beside the Op's own job; it
   // is carried separately on the doc so a dialect transforms it on its own.
   // A dialect's `header` note (#2257) is absent on github.
-  const { gatedNoticeDoc, ...workflow } = doc;
-  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}) } });
+  const { gatedNoticeDoc, reviewNoteDoc, ...workflow } = doc;
+  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}), ...(reviewNoteDoc ?? {}) } });
 }
 
 /**

package/src/components/generate-op-waves-pipeline.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
 import { generateGithubOpWavesPipeline } from "./generate-op-waves-pipeline";
+import { ACTION_PINS, usesRef } from "@intentius/chant/action-pins";
 
 const spec: OpWavesSpec = {
   name: "migrations",
@@ -26,7 +27,7 @@ describe("generateGithubOpWavesPipeline", () => {
     expect(yaml).toContain("run: chant run wave --spec waves.json --wave 2 --decide");
     expect(yaml).toMatch(/wave-2-prod-share-2:\n\s+runs-on: ubuntu-latest\n\s+needs:\n\s+- wave-2-prod-decide/);
     expect(yaml).toContain("run: chant run wave --spec waves.json --wave 2 --share 2");
-    expect(yaml).toContain("uses: actions/upload-artifact@v4");
+    expect(yaml).toContain(`uses: ${usesRef(ACTION_PINS.uploadArtifact4)}`);
     expect(yaml).toContain("name: migrations-wave-2-decision");
     expect(yaml).toContain("environment:\n      name: production");
   });

package/src/components/generate-op-waves-pipeline.ts

@@ -3,9 +3,17 @@
  *
  * One workflow for the whole spec, on a push to its branches (and by hand),
  * one run at a time. Each job is one of core's `opWaveJobs`: a wave, or a wide
- * wave's deciding job and share jobs, chained by `needs:` so a wave that waits
- * at its gate (exit 3) or fails stops every later wave. Re-running the failed
- * jobs after `chant approve` carries on from that wave.
+ * wave's deciding job and share jobs, chained by `needs:`. Re-running the
+ * failed jobs after `chant approve` carries on from that wave.
+ *
+ * Each job keeps its outcome file as an artifact whatever its exit code
+ * (#4322), and a job with `needs:` downloads every artifact of the run into
+ * the outcome directory first. A wave or deciding job after the first runs
+ * unless the run was cancelled (`if: !cancelled()`), so it runs after a
+ * failure in the wave before: it blocks the runs that depend on a failed one
+ * and applies the rest, and it stops by itself when an earlier wave waits at
+ * its gate (exit 3) or applied nothing for another reason. A share job still
+ * needs its deciding job to succeed.
  *
  * Every job checks out the full history, because the runner reads the gate
  * policy from the spec file at the base commit and records pending gates on
@@ -43,7 +51,7 @@
  * and cannot request one for another group's identity.
  */
 
-import { notifyVariables, opWaveGroupOf, opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { notifyVariables, opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
 import {
   assertEnvironment,
@@ -60,7 +68,7 @@ import {
   setupStepDoc,
 } from "@intentius/chant/ci-jobs";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
-import { checkoutStep, concurrency, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs";
+import { checkoutStep, concurrency, DOWNLOAD_ARTIFACT, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs";
 import { emitOpPipelineYAML, type GithubOpPipelineDoc } from "./generate-op-pipeline";
 
 /** The default image: it carries git, which the runner needs to read the base commit. */
@@ -71,6 +79,11 @@ export function opWaveRecordArtifact(spec: Pick<OpWavesSpec, "name">, wave: numb
   return `${spec.name}-wave-${wave}-decision`;
 }
 
+/** The artifact a job keeps its outcome file in (#4322). */
+export function opWaveOutcomeArtifact(spec: Pick<OpWavesSpec, "name">, jobName: string): string {
+  return `${spec.name}-${jobName}-outcome`;
+}
+
 /** The workflow document, before emission, and the jobs it holds. */
 export function buildGithubOpWavesDoc(
   spec: OpWavesSpec,
@@ -100,6 +113,10 @@ export function buildGithubOpWavesDoc(
     if (job.kind === "share") {
       steps.push(downloadArtifactStep(`Download wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), dirnameOf(job.record!)));
     }
+    if (job.needs.length > 0) {
+      // #4322: every artifact of the run, so the job reads each earlier job's outcome file.
+      steps.push({ name: "Download the earlier jobs' outcomes", uses: DOWNLOAD_ARTIFACT, with: { path: opWaveOutcomeDir(spec) } });
+    }
     const later: Array<Record<string, unknown>> = [];
     later.push(...[...(wave.setup ?? []), ...(group?.setup ?? [])].map(setupStepDoc), ...runSteps(options.beforeScript ?? []));
     later.push({ name: describeJob(job.kind, job.wave, wave.name, job.share, job.group), run: job.command.join(" ") });
@@ -108,12 +125,15 @@ export function buildGithubOpWavesDoc(
     if (job.kind === "decide") {
       steps.push(keepRecordStep(`Keep wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), job.record!));
     }
+    steps.push(keepRecordStep(`Keep the job's outcome`, opWaveOutcomeArtifact(spec, job.jobName), job.outcome));
     const environment = group?.environment ?? wave.environment;
     const idTokens = group?.idTokens ?? wave.idTokens;
     const idToken = idTokens !== undefined || cloud !== undefined;
     jobsDoc[job.jobName] = {
       "runs-on": githubRunsOn(group?.runner ?? wave.runner ?? spec.runner),
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+      // #4322: a wave's jobs run after a failure in the wave before; a share job runs only on its deciding job's success.
+      ...(job.needs.length > 0 && job.kind !== "share" ? { if: "!cancelled()" } : {}),
       container: image,
       ...(environment ? { environment: environmentDoc(environment) } : {}),
       // #3914: a job's own permissions replace the workflow's, so they repeat them.

package/src/components/generate-pipeline.test.ts

@@ -23,6 +23,7 @@ import { artifactRoot, generateGithubPipeline } from "./generate-pipeline";
 import { resolveComponentGraph, DependencyCycleError, UnknownDependencyError, type DriverComponent } from "@intentius/chant/components/driver";
 import { searchService } from "@intentius/chant/components/pilots/alb-ecs.pilot";
 import { ordersTable } from "@intentius/chant/components/pilots/dynamodb.pilot";
+import { ACTION_PINS, usesRef } from "@intentius/chant/action-pins";
 
 /** Real pilot components (#555) plus the shared-alb infra `search-service` depends on, as a realistic multi-wave input. */
 function pilotComponents(): DriverComponent[] {
@@ -67,21 +68,21 @@ describe("generateGithubPipeline: cross-stack output threading (artifacts)", ()
     // job, so it dumps them and uploads the file as a workflow artifact.
     const shared = jobs["shared-alb"];
     expect(runLines(shared).some((line) => line.includes("--dump-outputs shared-alb.outputs.json"))).toBe(true);
-    const uploadStep = shared.steps.find((s) => s.uses === "actions/upload-artifact@v4");
+    const uploadStep = shared.steps.find((s) => s.uses === `${usesRef(ACTION_PINS.uploadArtifact4)}`);
     expect(uploadStep?.with).toEqual({ name: "shared-alb-outputs", path: "shared-alb.outputs.json" });
 
     // Consumer: search-service downloads shared-alb's uploaded artifact and
     // seeds from the dumped file so its stackOutput() references resolve.
     const svc = jobs["search-service"];
-    const downloadStep = svc.steps.find((s) => s.uses === "actions/download-artifact@v4");
+    const downloadStep = svc.steps.find((s) => s.uses === `${usesRef(ACTION_PINS.downloadArtifact4)}`);
     expect(downloadStep?.with).toEqual({ name: "shared-alb-outputs", path: "." });
     expect(runLines(svc).some((line) => line.includes("--seed-outputs shared-alb.outputs.json"))).toBe(true);
 
     // A component nothing depends on neither dumps nor uploads an artifact.
     const orders = jobs["orders-table"];
     expect(runLines(orders).some((line) => line.includes("--dump-outputs"))).toBe(false);
-    expect(orders.steps.some((s) => s.uses === "actions/upload-artifact@v4")).toBe(false);
-    expect(orders.steps.some((s) => s.uses === "actions/download-artifact@v4")).toBe(false);
+    expect(orders.steps.some((s) => s.uses === `${usesRef(ACTION_PINS.uploadArtifact4)}`)).toBe(false);
+    expect(orders.steps.some((s) => s.uses === `${usesRef(ACTION_PINS.downloadArtifact4)}`)).toBe(false);
     expect(runLines(orders).some((line) => line.includes("--seed-outputs"))).toBe(false);
   });
 });
@@ -104,7 +105,7 @@ describe("generateGithubPipeline: structurally valid YAML", () => {
       expect(job.steps.length).toBeGreaterThan(0);
       // Every job starts with a checkout step — a job runs on a fresh runner
       // with no repo present, unlike GitLab's auto-cloned workspace.
-      expect(job.steps[0].uses).toBe("actions/checkout@v7");
+      expect(job.steps[0].uses).toBe(`${usesRef(ACTION_PINS.checkout7)}`);
     }
   });
 
@@ -327,7 +328,7 @@ describe("generateGithubPipeline: a promote job (#2575)", () => {
     const jobs = parsedJobs(result.yaml);
 
     const upload = jobs["api"].steps.find((s) => s.name === "Upload api build archive")!;
-    expect(upload.uses).toBe("actions/upload-artifact@v4");
+    expect(upload.uses).toBe(`${usesRef(ACTION_PINS.uploadArtifact4)}`);
     expect(upload.with).toEqual({
       name: "api-archive",
       path: "dist/images/api.tar",
@@ -339,7 +340,7 @@ describe("generateGithubPipeline: a promote job (#2575)", () => {
     const promote = jobs["promote-prod"];
     expect(promote.needs).toEqual(["api", "shared-alb", "worker"]);
     expect(promote.container).toBe("node:22");
-    const downloads = promote.steps.filter((s) => s.uses === "actions/download-artifact@v4");
+    const downloads = promote.steps.filter((s) => s.uses === `${usesRef(ACTION_PINS.downloadArtifact4)}`);
     expect(downloads.map((s) => s.with)).toEqual([
       { name: "api-archive", path: "dist/images" },
       { name: "worker-archive", path: "." },
@@ -440,7 +441,7 @@ describe("generateGithubPipeline: gated waves (#3049)", () => {
 
     const steps = parsed.jobs["wave-2"].steps;
     expect(steps[0].with).toEqual({ "fetch-depth": 0 });
-    expect(steps[1]).toMatchObject({ uses: "actions/download-artifact@v4", with: { name: "fan-out-record-wave-1", path: ".chant" } });
+    expect(steps[1]).toMatchObject({ uses: `${usesRef(ACTION_PINS.downloadArtifact4)}`, with: { name: "fan-out-record-wave-1", path: ".chant" } });
     // The default image is the pr-loop one: node:22, with OpenTofu installed when missing.
     expect(parsed.jobs["wave-2"]).toMatchObject({ container: "node:22" });
     expect(steps[2].run).toMatch(/^command -v tofu /);
@@ -449,7 +450,7 @@ describe("generateGithubPipeline: gated waves (#3049)", () => {
     );
     expect(steps[4]).toMatchObject({ if: "always()", with: { name: "fan-out-record-wave-2", path: ".chant/fan-out.json" } });
     // Wave 1 has nothing to download.
-    expect(parsed.jobs["wave-1"].steps.some((s) => s.uses === "actions/download-artifact@v4")).toBe(false);
+    expect(parsed.jobs["wave-1"].steps.some((s) => s.uses === `${usesRef(ACTION_PINS.downloadArtifact4)}`)).toBe(false);
   });
 
   test("a gated-wave pipeline has no promote job", () => {

package/src/components/generate-pipeline.ts

@@ -76,6 +76,10 @@ import {
   prLoopPostJob,
   prLoopSetup,
   PR_PLAN_NOTE_JOB,
+  PR_LOCK_JOB,
+  PR_UNLOCK_JOB,
+  PR_UNLOCK_COMMAND,
+  prLockCommand,
   prLoopWaveJobs,
   prLoopWithWaves,
   prEnvJobs,
@@ -90,8 +94,7 @@ import type {
   ComponentPipelineResult as GenerateGithubResult,
   PipelineMember,
 } from "@intentius/chant/lexicon";
-import { afterEarlierWave, checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
-import { actionRef } from "../action-pins";
+import { afterEarlierWave, CACHE_RESTORE, CACHE_SAVE, CHECKOUT, checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
 
 export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
 
@@ -270,13 +273,13 @@ function prLoopGithubDoc(
   const recordKey = (wave?: number) => `${recordPrefix}\${{ github.run_id }}-\${{ github.run_attempt }}${wave ? `-wave-${wave}` : ""}`;
   const restoreRecord = (wave?: number) => ({
     name: wave ? "Restore the newest record of this commit's apply" : "Restore the record of an earlier attempt at this commit",
-    uses: "actions/cache/restore@v4",
+    uses: CACHE_RESTORE,
     with: { path: recordPath, key: recordKey(wave), "restore-keys": recordPrefix },
   });
   const saveRecord = (wave?: number) => ({
     name: wave ? "Keep the record for the next wave and a re-run" : "Keep the record for a re-run",
     if: "always()",
-    uses: "actions/cache/save@v4",
+    uses: CACHE_SAVE,
     with: { path: recordPath, key: recordKey(wave) },
   });
   // #4296: the step that trades the job's OIDC token for its cloud identity, before the checkout.
@@ -380,7 +383,7 @@ function prLoopGithubDoc(
   const post = prLoopPostJob(forgeName, env, member?.name);
   const noteSteps: Array<Record<string, unknown>> = [
     // The target branch's commit: the chant this job runs is the target branch's, and none of the change's code is here.
-    { name: "Check out the target branch's commit", uses: actionRef("actions/checkout"), with: { ref: "${{ github.event.pull_request.base.sha }}" } },
+    { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}" } },
     ...runSteps(beforeScript),
     { name: "Take the plan report from the plan job", run: takeOverScript("plan", PR_LOOP_REPORT_DIR, forgeName) },
     { name: "Keep the plan report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: reportName(plan), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } },
@@ -388,9 +391,46 @@ function prLoopGithubDoc(
   ];
   // #4298: with a pull request environment the pull_request trigger fires on close too, and the plan skips that event.
   const prEnv = loop.prEnvironment ? prEnvGithubJobs(loop.forge ?? "github", image, beforeScript, extraScript, loop, member) : undefined;
+  // #4327: with ci.locks: plan the pull_request trigger fires on close too, for the unlock job, and the plan skips that event.
+  const locks = loop.locks === "plan";
+  const closes = Boolean(prEnv) || locks;
+  const lockJobs: Record<string, unknown> = locks
+    ? {
+        [PR_LOCK_JOB]: {
+          // The plan job's outputs carry the report; a plan that was skipped or failed leaves this job skipped.
+          needs: ["plan"],
+          if: "github.event_name == 'pull_request'",
+          "runs-on": GITHUB_RUNNER,
+          container: image,
+          permissions: { contents: "write", "pull-requests": "read", statuses: "write" },
+          steps: [
+            // The target branch's commit: this job pushes chant/lifecycle, so none of the change's code runs in it.
+            { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
+            ...runSteps(beforeScript),
+            { name: "Take the plan report from the plan job", run: takeOverScript("plan", PR_LOOP_REPORT_DIR, forgeName) },
+            {
+              name: "Lock the components the plan selected",
+              env: { PR_NUMBER: "${{ github.event.pull_request.number }}", HEAD_SHA: "${{ github.event.pull_request.head.sha }}", GITHUB_TOKEN: GITHUB_JOB_TOKEN },
+              run: prLockCommand(forgeName),
+            },
+          ],
+        },
+        [PR_UNLOCK_JOB]: {
+          if: "github.event_name == 'pull_request' && github.event.action == 'closed'",
+          "runs-on": GITHUB_RUNNER,
+          container: image,
+          permissions: { contents: "write" },
+          steps: [
+            { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
+            ...runSteps(beforeScript),
+            { name: "Release the pull request's locks", env: { PR_NUMBER: "${{ github.event.pull_request.number }}" }, run: PR_UNLOCK_COMMAND },
+          ],
+        },
+      }
+    : {};
   const jobsDoc: Record<string, unknown> = {
     plan: {
-      if: prEnv ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
+      if: closes ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
       "runs-on": GITHUB_RUNNER,
       container: image,
       permissions: withIdToken({ contents: "read" }),
@@ -406,6 +446,7 @@ function prLoopGithubDoc(
       permissions: { actions: "read", contents: "read", "pull-requests": "write", statuses: "write" },
       steps: noteSteps,
     },
+    ...lockJobs,
     ...Object.fromEntries(applyJobs),
     ...(prEnv ? prEnv.jobs : {}),
   };
@@ -415,6 +456,7 @@ function prLoopGithubDoc(
     : forgejo
       ? { pull_request: { branches: [branch] }, push: { branches: [branch], tags: [GREEN_TAG_PATTERN] } }
       : { pull_request: { branches: [branch] }, push: { branches: [branch] }, workflow_run: { workflows: [GREEN_TICK_WORKFLOW], types: ["completed"] }, workflow_dispatch: {} };
+  if (closes) on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
   if (prEnv) {
     on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
     on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
@@ -428,10 +470,16 @@ function prLoopGithubDoc(
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", PR_PLAN_NOTE_JOB, ...applyNames, ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
+    stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...applyNames, ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
     jobs: [
       { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
       { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
+      ...(locks
+        ? [
+            { jobName: PR_LOCK_JOB, component: "pull request lock", stage: PR_LOCK_JOB, needs: ["plan"] },
+            { jobName: PR_UNLOCK_JOB, component: "pull request unlock", stage: PR_UNLOCK_JOB, needs: [] },
+          ]
+        : []),
       ...applyNames.map((name, i) => ({
         jobName: name,
         component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
@@ -519,7 +567,7 @@ function prEnvGithubJobs(
     permissions: writes,
     steps: [
       // The target branch's commit: the chant this job runs is the target branch's, and none of the change's code is here.
-      { name: "Check out the target branch's commit", uses: actionRef("actions/checkout"), with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
+      { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
       ...runSteps(beforeScript),
       { name: "Take the environment's report from the env-up job", run: takeOverScript("env-up", PR_ENV_REPORT_DIR, forge) },
       keep("env-up"),
@@ -534,7 +582,7 @@ function prEnvGithubJobs(
     permissions: withIdToken(writes),
     steps: [
       ...tradeStep,
-      { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0, ...(ref ? { ref } : {}) } },
+      { uses: CHECKOUT, with: { "fetch-depth": 0, ...(ref ? { ref } : {}) } },
       ...runSteps(prLoopSetup(image)),
       ...runSteps(beforeScript),
       { name, env: j.env, run: j.command },