@intentius/chant-lexicon-github 0.124.40 → 0.124.42

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

@@ -0,0 +1,167 @@
+/**
+ * #4295: in the generated pull-request workflow, no step that runs the pull
+ * request's code holds a forge token. The plan job uses the job's token for
+ * its checkout's fetches alone, every later step starts without the token
+ * variables, and the plan step is the job's last and hands its report on as
+ * the job's outputs. The plan-note job, which runs none of the change's
+ * code, posts.
+ *
+ * The behaviour tests run the generated steps with `sh`, as a forge runs
+ * them, with every token variable set, and `chant ci run plan` replaced by a
+ * line that prints what the step can see.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { dropForgeTokens, FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+  { name: "app", dependsOn: ["net"], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] },
+];
+
+interface Step {
+  name?: string;
+  id?: string;
+  if?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+}
+interface Job {
+  needs?: string[];
+  if?: string;
+  permissions?: Record<string, string>;
+  outputs?: Record<string, string>;
+  steps: Step[];
+}
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const SECRET = "ghs_generated_job_secret_4295";
+const TOKENS = Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${SECRET}_${v}`]));
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+const PLAN_LINE = /^chant ci run plan .*$/m;
+
+/** The pipeline with a build, a before-script line and an after-script line, so every kind of step is there. */
+function workflow(extra: Record<string, unknown> = {}): { jobs: Record<string, Job> } {
+  const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", image: "example/ci:1", beforeScript: ["npm ci"], extraScript: ["echo after"], prLoop: { build: true, ...extra } });
+  return parseYAML(yaml) as { jobs: Record<string, Job> };
+}
+
+describe("the generated plan job holds no forge token while the change's code runs (#4295)", () => {
+  const doc = workflow();
+  const plan = doc.jobs.plan!;
+  const note = doc.jobs["plan-note"]!;
+
+  test("only the checkout step is given the job's token, and only for its fetches", () => {
+    const [checkout, ...rest] = plan.steps;
+    expect(checkout!.uses).toBeUndefined();
+    expect(checkout!.env).toEqual({ CHANT_CHECKOUT_TOKEN: "${{ github.token }}" });
+    for (const step of rest) {
+      expect(JSON.stringify(step)).not.toContain("github.token");
+      for (const name of FORGE_TOKEN_VARS) expect(step.env ?? {}).not.toHaveProperty(name);
+    }
+    // The token itself can read the repository and nothing else.
+    expect(plan.permissions).toEqual({ contents: "read" });
+  });
+
+  test("every step after the checkout starts by dropping the token variables, and none is an action", () => {
+    for (const step of plan.steps.slice(1)) {
+      expect(step.uses).toBeUndefined();
+      expect(step.run!.split("\n")[0]).toBe(dropForgeTokens("sh"));
+    }
+  });
+
+  test("the plan step is the job's last: no upload, cache or checkout post step runs after the change's code", () => {
+    const last = plan.steps.at(-1)!;
+    expect(last.id).toBe("plan");
+    expect(last.run).toMatch(PLAN_LINE);
+    // The after-script lines run inside it, not as steps of their own.
+    expect(last.run!.trimEnd().split("\n").at(-1)).toBe("echo after");
+    expect(plan.outputs).toEqual({ report_0: "${{ steps.plan.outputs.report_0 }}" });
+  });
+
+  test("the plan-note job checks out the target branch's commit, and only it can write the note and the status", () => {
+    expect(note.needs).toEqual(["plan"]);
+    expect(note.if).toContain("needs.plan.result == 'failure'");
+    expect(note.steps[0]).toMatchObject({ uses: expect.stringMatching(/^actions\/checkout@/), with: { ref: "${{ github.event.pull_request.base.sha }}" } });
+    expect(note.permissions).toEqual({ actions: "read", contents: "read", "pull-requests": "write", statuses: "write" });
+    const post = note.steps.at(-1)!;
+    expect(post.env).toMatchObject({ GITHUB_TOKEN: "${{ github.token }}", HEAD_SHA: "${{ github.sha }}", PLAN_RESULT: "${{ needs.plan.result }}" });
+    expect(post.run).toBe('chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge github --result "$PLAN_RESULT"');
+    // The note job runs no build, no lint and no plan: none of the change's code.
+    expect(JSON.stringify(note)).not.toMatch(/chant (build|lint|ci run)/);
+  });
+});
+
+/** Run one generated step as a forge does: its script as a file, `sh -e`, with the job's tokens in the environment. */
+function runStep(step: Step, cwd: string, env: Record<string, string>): number | null {
+  const file = join(cwd, "..", `step-${Math.random().toString(36).slice(2)}.sh`);
+  writeFileSync(file, step.run!);
+  return spawnSync("sh", ["-e", file], { cwd, env: { ...BASE, ...TOKENS, ...env }, encoding: "utf-8" }).status;
+}
+
+describe("the generated steps, run, see no forge token and hand the report on (#4295)", () => {
+  const doc = workflow();
+
+  test("each step after the checkout, and every process it starts, sees none of the token variables", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-step-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(work);
+    const seen = join(top, "seen");
+    mkdirSync(seen);
+    const output = join(top, "github-output");
+    const steps = doc.jobs.plan!.steps.slice(1);
+    steps.forEach((step, i) => {
+      // The step's own lines become a probe; the plan line also writes a report, as pr-plan would.
+      const probe = `env > "${seen}/${i}.env"; sh -c 'env' >> "${seen}/${i}.env"`;
+      const report = 'mkdir -p .chant/pr && echo \'{"stage":"plan"}\' > .chant/pr/pr-plan.json && echo note > .chant/pr/pr-note.md';
+      // The generated drop line and hand-on lines run as they are; the step's own commands become the probe.
+      const lines = step.run!.split("\n");
+      const handover = lines.filter((l) => l.startsWith("chant_report=") || l.startsWith("chant_handover") || l.startsWith("trap "));
+      const body = [lines[0], ...handover, probe, ...(PLAN_LINE.test(step.run!) ? [report] : [])].join("\n");
+      const status = runStep({ run: body }, work, { GITHUB_OUTPUT: output, BASE_SHA: "b".repeat(40), PR_NUMBER: "7" });
+      expect(status, step.name ?? step.run!.split("\n")[1]).toBe(0);
+    });
+    for (let i = 0; i < steps.length; i++) {
+      const env = readFileSync(join(seen, `${i}.env`), "utf-8");
+      expect(env).not.toContain(SECRET);
+    }
+    // The plan step handed its report on as the job's output.
+    expect(readFileSync(output, "utf-8")).toMatch(/^report_0=\S+$/m);
+  });
+
+  test("the note job's take-over step writes the plan step's report back from that output", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-note-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(join(work, ".chant", "pr"), { recursive: true });
+    writeFileSync(join(work, ".chant", "pr", "pr-plan.json"), '{"stage":"plan"}\n');
+    const output = join(top, "github-output");
+    const planStep = doc.jobs.plan!.steps.at(-1)!;
+    const handOn = planStep.run!.split("\n").filter((l, n) => n === 0 || l.startsWith("chant_report=") || l.startsWith("chant_handover") || l.startsWith("trap ")).join("\n");
+    expect(runStep({ run: handOn }, work, { GITHUB_OUTPUT: output })).toBe(0);
+    const value = readFileSync(output, "utf-8").trim().slice("report_0=".length);
+
+    const noteWork = join(top, "note");
+    mkdirSync(noteWork);
+    const take = doc.jobs["plan-note"]!.steps.find((s) => s.name === "Take the plan report from the plan job")!;
+    // The forge fills the expression with toJSON of the output: a JSON string on one line.
+    const filled = take.run!.replace("${{ toJSON(needs.plan.outputs.report_0) }}", JSON.stringify(value));
+    expect(runStep({ run: filled }, noteWork, {})).toBe(0);
+    expect(existsSync(join(noteWork, ".chant", "pr", "pr-plan.json"))).toBe(true);
+    expect(readFileSync(join(noteWork, ".chant", "pr", "pr-plan.json"), "utf-8")).toBe('{"stage":"plan"}\n');
+  });
+});

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

@@ -0,0 +1,219 @@
+/**
+ * #4296: the pull-request workflow's plan job trades its OIDC token for the
+ * plan identity before the change is checked out, and the change's code
+ * never holds a token, a way to request one, or the apply identity.
+ *
+ * The behaviour tests run the generated steps with `sh`, as a forge runner
+ * does: the trade step against a local emulator of the token URL and the
+ * clouds (@intentius/chant/__fixtures__/oidc-emulator), then each later
+ * step with the runner's token request variables still set and what the
+ * trade left in GITHUB_ENV, its own commands replaced by a probe that
+ * prints what it sees and tries to request a token. Test values only.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { dropForgeTokens, FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { OIDC_REQUEST_VARS, resolveCloudIdentity, TRADE_SPEC_ENV, tradeIdentities, type PipelineCloudIdentity } from "@intentius/chant/ci-identity";
+import { emulatedCredentials, EMULATED_JWT_PREFIX, EMULATED_REQUEST_TOKEN, startOidcEmulator, type OidcEmulator } from "@intentius/chant/__fixtures__/oidc-emulator";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const run = promisify(execFile);
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+  { name: "app", dependsOn: ["net"], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] },
+];
+
+const PLAN_ROLE = "arn:aws:iam::111111111111:role/prod-plan";
+const APPLY_ROLE = "arn:aws:iam::111111111111:role/prod-apply";
+const IDENTITY = resolveCloudIdentity(
+  {
+    aws: { rules: [{ environments: ["prod"], plan: PLAN_ROLE, apply: APPLY_ROLE }] },
+    gcp: { provider: "projects/123/locations/global/workloadIdentityPools/ci/providers/forge", rules: [{ plan: "plan@test.iam.gserviceaccount.com", apply: "apply@test.iam.gserviceaccount.com" }] },
+    azure: { tenantId: "test-tenant", rules: [{ plan: "plan-client", apply: "apply-client" }] },
+  },
+  "prod",
+)!;
+const APPLY_IDENTITIES = tradeIdentities(IDENTITY.apply);
+
+interface Step {
+  name?: string;
+  id?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  "working-directory"?: string;
+}
+interface Job {
+  permissions?: Record<string, string>;
+  steps: Step[];
+}
+
+function workflow(identity: PipelineCloudIdentity | undefined, extra: Record<string, unknown> = {}): { jobs: Record<string, Job> } {
+  const { yaml } = generateGithubPipeline(ESTATE, {
+    env: "prod",
+    image: "example/ci:1",
+    beforeScript: ["npm ci"],
+    extraScript: ["echo after"],
+    prLoop: { build: true, applyOnMerge: true, ...(identity ? { identity } : {}), ...extra },
+  });
+  return parseYAML(yaml) as { jobs: Record<string, Job> };
+}
+
+const TRADE_NAME = /^Trade the job's OIDC token for the (plan|apply) identity$/;
+const tradeOf = (job: Job): Record<string, unknown> => JSON.parse(job.steps[0]!.env![TRADE_SPEC_ENV]!) as Record<string, unknown>;
+
+describe("the generated jobs' cloud identities (#4296)", () => {
+  const doc = workflow(IDENTITY);
+  const plan = doc.jobs.plan!;
+
+  test("the plan job's first step trades for the plan identity, before the checkout", () => {
+    expect(plan.steps[0]!.name).toMatch(TRADE_NAME);
+    expect(plan.steps[0]!.name).toContain("plan identity");
+    expect(plan.steps[0]!.uses).toBeUndefined();
+    expect(plan.steps[0]!.run).toMatch(/^\(cd \/ && node -e '/);
+    expect(plan.steps[1]!.name).toBe("Check out the change");
+    expect(tradeOf(plan)).toEqual(IDENTITY.plan);
+    expect(plan.permissions).toEqual({ contents: "read", "id-token": "write" });
+  });
+
+  test("the plan job names no apply identity anywhere", () => {
+    const text = JSON.stringify(plan);
+    for (const id of APPLY_IDENTITIES) expect(text).not.toContain(id);
+  });
+
+  test("every step after the checkout starts by dropping the forge tokens and the OIDC request variables", () => {
+    for (const step of plan.steps.slice(2)) expect(step.run!.split("\n")[0]).toBe(dropForgeTokens("sh", OIDC_REQUEST_VARS));
+  });
+
+  test("the record job trades for the plan identity and the apply job for the apply identity, each before its checkout", () => {
+    const record = doc.jobs.record!;
+    const apply = doc.jobs.apply!;
+    expect(record.steps[0]!.name).toContain("plan identity");
+    expect(tradeOf(record)).toEqual(IDENTITY.plan);
+    expect(apply.steps[0]!.name).toContain("apply identity");
+    expect(tradeOf(apply)).toEqual(IDENTITY.apply);
+    for (const job of [record, apply]) {
+      expect(job.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+      expect(job.permissions!["id-token"]).toBe("write");
+    }
+    expect(JSON.stringify(record)).not.toContain(APPLY_ROLE);
+  });
+
+  test("with a gate per wave, every wave's apply job trades for the apply identity", () => {
+    const waves = workflow(IDENTITY, { waveGate: "prod" }).jobs;
+    const names = Object.keys(waves).filter((n) => n.startsWith("apply-wave-"));
+    expect(names.length).toBe(2);
+    for (const n of names) expect(tradeOf(waves[n]!)).toEqual(IDENTITY.apply);
+  });
+
+  test("the plan-note job requests no token and trades nothing", () => {
+    const note = doc.jobs["plan-note"]!;
+    expect(note.permissions!["id-token"]).toBeUndefined();
+    expect(JSON.stringify(note)).not.toContain(TRADE_SPEC_ENV);
+  });
+
+  test("without identity no job requests a token, and the plan job is as #4295 left it", () => {
+    const plain = workflow(undefined);
+    for (const job of Object.values(plain.jobs)) {
+      expect(job.permissions?.["id-token"]).toBeUndefined();
+      expect(job.steps.some((s) => TRADE_NAME.test(s.name ?? ""))).toBe(false);
+    }
+    expect(plain.jobs.plan!.steps[1]!.run!.split("\n")[0]).toBe(dropForgeTokens("sh"));
+  });
+});
+
+const dirs: string[] = [];
+let emu: OidcEmulator;
+beforeAll(async () => {
+  emu = await startOidcEmulator();
+});
+afterAll(async () => {
+  await emu.close();
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+const FORGE_SECRET = "ghs_identity_secret_4296";
+const TOKENS = Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${FORGE_SECRET}_${v}`]));
+
+/** Run one step's script as a forge does: a file, `sh -e`. */
+async function runStep(script: string, cwd: string, env: Record<string, string>): Promise<{ code: number; stdout: string; stderr: string }> {
+  const file = join(cwd, "..", `step-${Math.random().toString(36).slice(2)}.sh`);
+  writeFileSync(file, script);
+  try {
+    const r = await run("sh", ["-e", file], { cwd, env: { ...BASE, ...env } });
+    return { code: 0, stdout: r.stdout, stderr: r.stderr };
+  } catch (e) {
+    const err = e as { code: number; stdout: string; stderr: string };
+    return { code: err.code, stdout: err.stdout, stderr: err.stderr };
+  }
+}
+
+/** GITHUB_ENV's `NAME=value` lines as the runner applies them to the job's later steps. */
+const githubEnv = (text: string): Record<string, string> =>
+  Object.fromEntries(text.split("\n").filter((l) => l.includes("=")).map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
+
+/** A probe: what the step's shell and a child see, and whether a request for an apply-audience token succeeds. */
+const PROBE = [
+  'env > "$SEEN"',
+  `sh -c 'env' >> "$SEEN"`,
+  `node -e 'const u=process.env.ACTIONS_ID_TOKEN_REQUEST_URL,k=process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;if(!u||!k){console.log("no-request-vars");process.exit(0)}fetch(u+"&audience=sts.amazonaws.com",{headers:{authorization:"bearer "+k}}).then(r=>r.text()).then(t=>console.log("minted:"+t))' >> "$SEEN"`,
+].join("\n");
+
+describe("the generated plan job, run: the change's code never holds a token or the apply identity (#4296)", () => {
+  test("the trade mints and trades for the plan identity alone; every later step sees plan credentials and nothing to request a token with", async () => {
+    const identity: PipelineCloudIdentity = { plan: emu.pointAt(IDENTITY.plan), apply: emu.pointAt(IDENTITY.apply) };
+    const plan = workflow(identity).jobs.plan!;
+    const top = mkdtempSync(join(tmpdir(), "chant-identity-job-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(work);
+    const envFile = join(top, "github-env");
+    writeFileSync(envFile, "");
+    // The runner gives every step of a job with id-token: write the request variables, and the forge tokens.
+    const runner = { ...emu.requestEnv, ...TOKENS, GITHUB_ENV: envFile };
+    const before = { minted: emu.log.minted.length, assumed: emu.log.assumed.length, impersonated: emu.log.impersonated.length, clients: emu.log.clients.length };
+
+    const trade = plan.steps[0]!;
+    const traded = await runStep(trade.run!, work, { ...runner, ...trade.env });
+    expect(traded.stderr).not.toContain("failed");
+    expect(traded.code).toBe(0);
+    expect(emu.log.minted.length - before.minted).toBe(3);
+    expect(emu.log.assumed.slice(before.assumed).map((a) => a.role)).toEqual([PLAN_ROLE]);
+    expect(emu.log.impersonated.slice(before.impersonated)).toEqual(["plan@test.iam.gserviceaccount.com"]);
+    expect(emu.log.clients.slice(before.clients).map((c) => c.clientId)).toEqual(["plan-client"]);
+    const left = githubEnv(readFileSync(envFile, "utf-8"));
+    expect(left.AWS_ACCESS_KEY_ID).toBe(emulatedCredentials(PLAN_ROLE).accessKeyId);
+
+    const later = plan.steps.slice(2);
+    expect(later.length).toBeGreaterThan(2);
+    const mintedAfterTrade = emu.log.minted.length;
+    for (const [i, step] of later.entries()) {
+      const seen = join(top, `seen-${i}`);
+      const lines = step.run!.split("\n");
+      const r = await runStep([lines[0], PROBE].join("\n"), work, { ...runner, ...left, ...(step.env ?? {}), SEEN: seen });
+      expect(r.code, step.name ?? lines[1]).toBe(0);
+      const text = readFileSync(seen, "utf-8");
+      expect(text).toContain(`AWS_ACCESS_KEY_ID=${emulatedCredentials(PLAN_ROLE).accessKeyId}`);
+      expect(text).toContain("no-request-vars");
+      expect(text).not.toContain("minted:");
+      expect(text).not.toContain(EMULATED_JWT_PREFIX);
+      expect(text).not.toContain(EMULATED_REQUEST_TOKEN);
+      expect(text).not.toContain(FORGE_SECRET);
+      for (const id of APPLY_IDENTITIES) expect(text).not.toContain(id);
+      expect(text).not.toContain(emulatedCredentials(APPLY_ROLE).accessKeyId);
+      for (const v of OIDC_REQUEST_VARS) expect(text).not.toMatch(new RegExp(`^${v}=`, "m"));
+    }
+    // No step after the trade minted a token.
+    expect(emu.log.minted.length).toBe(mintedAfterTrade);
+    expect(emu.log.assumed.some((a) => a.role === APPLY_ROLE)).toBe(false);
+  });
+});

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

@@ -12,6 +12,7 @@ import { describe, expect, test } from "vitest";
 import { parseYAML } from "@intentius/chant/yaml";
 import type { DriverComponent } from "@intentius/chant/components/driver";
 import { githubBaseFallback, greenCheckout, prApplyGroup, prApplyRecordKey, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
+import { dropForgeTokens } from "@intentius/chant/ci-handover";
 import { generateGithubPipeline } from "./generate-pipeline";
 
 const ESTATE: DriverComponent[] = [
@@ -38,6 +39,14 @@ interface Step {
   env?: Record<string, string>;
   with?: Record<string, unknown>;
 }
+/** A plan job's run step without the line that drops the forge tokens (#4295). */
+const headLines = (run: string | undefined): string[] => {
+  const lines = (run ?? "").trimEnd().split("\n");
+  return lines[0] === dropForgeTokens("sh") ? lines.slice(1) : lines;
+};
+/** The plan step's command: its last line. */
+const lastLine = (run: string | undefined): string | undefined => (run ?? "").trimEnd().split("\n").at(-1);
+
 interface Job {
   if: string;
   permissions: Record<string, string>;
@@ -61,18 +70,20 @@ describe("the GitHub pull-request workflow", () => {
     expect(doc.jobs.plan.if).toBe("github.event_name == 'pull_request'");
     expect(doc.jobs.record.if).toBe("github.event_name == 'push'");
     expect(doc.jobs.apply.if).toBe("github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'");
-    expect(result.jobs.map((j) => j.jobName)).toEqual(["plan", "record", "apply"]);
+    expect(result.jobs.map((j) => j.jobName)).toEqual(["plan", "plan-note", "record", "apply"]);
     expect(result.jobs.find((j) => j.jobName === "apply")!.needs).toEqual([]);
   });
 
   test("the plan job measures from the pull request's base and cannot push; the apply job can, one at a time", () => {
     const plan = doc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!;
     // #4156: the job runs pr-plan through chant ci run, in its own checkout, and pushes no record from the pull request's code.
-    expect(plan.run).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
+    expect(lastLine(plan.run)).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
     expect(plan.env).toMatchObject({ BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}" });
     // The runner key is an optional secret: unset, the expression is empty and the record is unsigned.
     expect(plan.env?.CHANT_RUNNER_KEY).toBe("${{ secrets.CHANT_RUNNER_KEY }}");
-    expect(doc.jobs.plan.permissions).toEqual({ contents: "read", "pull-requests": "write", statuses: "write" });
+    // #4295: the plan job only reads; the plan-note job writes the note and the status.
+    expect(doc.jobs.plan.permissions).toEqual({ contents: "read" });
+    expect(doc.jobs["plan-note"].permissions).toEqual({ actions: "read", contents: "read", "pull-requests": "write", statuses: "write" });
 
     const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
     // #4168: ci run builds pr-apply without --require-review unless the pipeline asks for it.
@@ -82,7 +93,10 @@ describe("the GitHub pull-request workflow", () => {
     expect(apply.env).toEqual({ GITHUB_TOKEN: "${{ github.token }}", CHANT_RUNNER_KEY: "${{ secrets.CHANT_RUNNER_KEY }}" });
     expect(doc.jobs.apply.permissions.contents).toBe("write");
     expect(doc.jobs.apply.concurrency).toEqual({ group: "chant-apply-prod", "cancel-in-progress": false });
-    for (const job of Object.values(doc.jobs)) expect(job.steps[0].with).toEqual({ "fetch-depth": 0 });
+    for (const [name, job] of Object.entries(doc.jobs)) if (!name.startsWith("plan")) expect(job.steps[0].with).toEqual({ "fetch-depth": 0 });
+    // #4295: the plan job checks out with a script, and the note job checks out the target branch's commit.
+    expect(doc.jobs.plan.steps[0].uses).toBeUndefined();
+    expect(doc.jobs["plan-note"].steps[0].with).toEqual({ ref: "${{ github.event.pull_request.base.sha }}" });
   });
 
   test("a first push's all-zero github.event.before is settled in the record's own shell, before pr-record reads it (#4004)", () => {
@@ -179,7 +193,7 @@ describe("the GitHub pull-request workflow", () => {
     expect(mdoc.defaults).toEqual({ run: { "working-directory": "infra/network" } });
     const plan = mdoc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!;
     // ci run finds the member from the directory it runs in and passes --member to pr-plan and pr-apply.
-    expect(plan.run).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
+    expect(lastLine(plan.run)).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
     expect(prLoopJobs("github", "prod", {}, "network")[0]!.command).toContain("--member network");
     const apply = mdoc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
     expect(mdoc.jobs.apply.concurrency).toEqual({ group: "chant-apply.network.prod", "cancel-in-progress": false });
@@ -187,10 +201,16 @@ describe("the GitHub pull-request workflow", () => {
     expect(apply.run).toContain("--in-place");
     const restore = mdoc.jobs.apply.steps.find((s) => s.uses === "actions/cache/restore@v4")!;
     expect(restore.with).toMatchObject({ path: "infra/network/.chant/pr-resume/pr-apply.json", "restore-keys": "chant-apply.network.prod-${{ github.sha }}-" });
-    for (const job of Object.values(mdoc.jobs)) {
+    // #4295: the plan job uploads nothing; the plan-note job keeps its report.
+    expect(mdoc.jobs.plan.steps.some((s) => s.uses?.startsWith("actions/upload-artifact"))).toBe(false);
+    for (const [name, job] of Object.entries(mdoc.jobs)) {
+      if (name === "plan") continue;
       const keep = job.steps.find((s) => s.uses?.startsWith("actions/upload-artifact"))!;
       expect(keep.with?.path).toBe("infra/network/.chant/pr");
     }
+    // The checkout runs at the repository's root, before the member's directory exists.
+    expect((mdoc.jobs.plan.steps[0] as Record<string, unknown>)["working-directory"]).toBe(".");
+    expect(mdoc.jobs["plan-note"].steps.at(-1)!.run).toContain("--member network");
   });
 
   test("no two member and environment pairs share an apply group or record key", () => {
@@ -236,8 +256,8 @@ describe("the github pull-request pipeline with build (#4088)", () => {
 
   test("builds, then lints, before pr-plan and pr-apply", () => {
     for (const job of ["plan", "apply"]) {
-      const runs = doc.jobs[job].steps.map((s: { run?: string }) => s.run ?? "").filter(Boolean);
-      const i = runs.findIndex((r: string) => r.startsWith("chant components pr-"));
+      const runs = doc.jobs[job].steps.map((s: { run?: string }) => headLines(s.run).join("\n")).filter(Boolean);
+      const i = runs.findIndex((r: string) => r.includes(`chant ci run ${job}`));
       expect(runs.slice(i - 2, i)).toEqual(["chant build --env prod", "chant lint"]);
     }
   });
@@ -266,7 +286,7 @@ describe("the GitHub pull-request workflow records on merge by default (#4168)",
   });
 
   test("a push runs the record job, which applies nothing and keeps no resume record", () => {
-    expect(result.jobs.map((j) => j.jobName)).toEqual(["plan", "record"]);
+    expect(result.jobs.map((j) => j.jobName)).toEqual(["plan", "plan-note", "record"]);
     expect(doc.jobs.apply).toBeUndefined();
     expect(doc.jobs.record.if).toBe("github.event_name == 'push'");
     const run = doc.jobs.record.steps.find((s) => s.run?.includes("ci run record"))!;

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

@@ -80,9 +80,10 @@ describe("the GitHub pull-request workflow with a gate per wave (#4003)", () =>
   });
 
   test("keeps the plan and record jobs, and writes one apply job per wave, each needing the one before", () => {
-    expect(Object.keys(doc.jobs)).toEqual(["plan", "record", "apply-wave-1", "apply-wave-2", "apply-wave-3"]);
+    expect(Object.keys(doc.jobs)).toEqual(["plan", "plan-note", "record", "apply-wave-1", "apply-wave-2", "apply-wave-3"]);
     expect(result.jobs.map((j) => [j.jobName, j.needs])).toEqual([
       ["plan", []],
+      ["plan-note", ["plan"]],
       ["record", []],
       ["apply-wave-1", []],
       ["apply-wave-2", ["apply-wave-1"]],
@@ -96,7 +97,9 @@ describe("the GitHub pull-request workflow with a gate per wave (#4003)", () =>
     for (const k of [1, 2, 3]) {
       const job = doc.jobs[`apply-wave-${k}`]!;
       // #4168 step 9: the waves apply the newest green commit once the tick ran.
-      expect(job.if).toBe("github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'");
+      // #4291: a wave after the first runs after one that failed, so a failure blocks only its dependents.
+      const onGreen = "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
+      expect(job.if).toBe(k === 1 ? onGreen : `!cancelled() && needs.apply-wave-${k - 1}.result != 'skipped' && (${onGreen})`);
       expect(job.concurrency).toEqual({ group: "chant-apply-prod", "cancel-in-progress": false });
       expect(job.permissions.contents).toBe("write");
       const run = job.steps.find((s) => s.run?.includes("ci run apply"))!.run!;
@@ -121,7 +124,7 @@ describe("the GitHub pull-request workflow with a gate per wave (#4003)", () =>
 
   test("without --wave-gate the workflow is the one apply job it was", () => {
     const plain = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } });
-    expect(plain.jobs.map((j) => j.jobName)).toEqual(["plan", "record", "apply"]);
+    expect(plain.jobs.map((j) => j.jobName)).toEqual(["plan", "plan-note", "record", "apply"]);
     expect(plain.yaml).not.toContain("--wave");
   });