@intentius/chant 0.124.32 → 0.124.34

package/src/cli/registry.ts

@@ -311,8 +311,10 @@ export interface ParsedArgs {
   /**
    * `chant components pr-apply --require-review` (#3183) — count an approval
    * only when its approver has a standing approving review on the pull
-   * request. Needs `--forge`. `chant ci run apply --no-require-review`
-   * (#4156) sets it false, for a pipeline generated with `requireReview: false`.
+   * request. Needs `--forge`. `chant ci run apply --require-review`
+   * passes it on, and `chant build --pr-loop --require-review` generates a
+   * pipeline that does (#4168); `--no-require-review` (#4156) sets it false,
+   * which is the default.
    */
   requireReview?: boolean;
   /**
@@ -323,12 +325,20 @@ export interface ParsedArgs {
   reportUrl?: string;
   /**
    * `chant build --components --generate <lexicon> --pr-loop` (#3183) —
-   * generate the pull-request pipeline: plan on the pull request, apply on
-   * merge bound to the approved digest.
+   * generate the pull-request pipeline: plan on the pull request, and on
+   * merge record the plan (#4168), or apply it with `--apply-on-merge`.
    */
   prLoop?: boolean;
+  /**
+   * `chant build --pr-loop --apply-on-merge` and `chant ci serve
+   * --apply-on-merge` (#4168): on merge apply the approved plan, as before
+   * #4168, in place of recording it. Opt-in: a merge deploys nothing without it.
+   */
+  applyOnMerge?: boolean;
   /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
   prBuild?: boolean;
+  /** `chant ci serve --build-command <line>` (#4169) — the line that builds a commit a `ci/build/<sha>` tag asks for, in a worktree of it. */
+  ciBuildCommand?: string;
   /** `chant build --pr-loop --pr-build-command <line>` (#4088) — the build line to run in place of `chant build --env <env>`. */
   prBuildCommand?: string;
   /**
@@ -457,8 +467,10 @@ export interface ParsedArgs {
   label?: string;
   /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. */
   branch?: string;
-  /** `chant ci workflow --workflow <name>`, repeatable (#3573): a workflow whose completion triggers a tick, beside those the scan finds. */
+  /** `chant ci workflow --workflow <name>`, repeatable (#3573): a workflow whose completion triggers a tick, beside those the scan finds. Also `chant ci init --workflow <name>` (#4168 step 6), the prescribed workflow to set up. */
   ciWorkflows?: string[];
+  /** `chant ci init --security <group>`, repeatable (#4168 step 6): a security group to turn on. */
+  securityGroups?: string[];
   /** `chant ci run plan|apply --commit <sha>` (#4094): the commit the job runs at. Default `HEAD`. */
   commit?: string;
   /** `chant ci run --pass-env <NAME>`, repeatable (#4094): a variable of the runner's environment the job gets, beside the few it always gets. */
@@ -511,6 +523,10 @@ export interface ParsedArgs {
   unsigned?: boolean;
   /** `chant ci run --in-place` (#4156): run the job in this checkout at HEAD, as a generated forge job does. */
   ciInPlace?: boolean;
+  /** `chant ci run --require-runner-start` (#4147): refuse the job unless a runner-start statement names it. */
+  requireRunnerStart?: boolean;
+  /** `chant ci runner-start sign --job <json|@file>` (#4147): the CI job a runner was started for. */
+  ciJob?: string;
   /** `chant ci run --no-push` (#4156): write the run record on the local chant/lifecycle and push nothing. */
   noPush?: boolean;
   /** `chant ci serve|run --setup-key --trust --principal <name>` (#4099): the principal the runner key is listed for. */

package/src/components/deploy-inputs.test.ts

@@ -0,0 +1,108 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { componentDeployInputs, directoryDigest, directoryFiles, stepInputRefs } from "./deploy-inputs";
+import { componentPlanDigest } from "./gate-plan";
+import type { DriverComponent, DriverPhase } from "./driver";
+
+let root: string;
+
+const write = (path: string, content: string): void => {
+  mkdirSync(dirname(join(root, path)), { recursive: true });
+  writeFileSync(join(root, path), content);
+};
+const deploy = (...steps: Array<Record<string, unknown>>): DriverPhase[] => [{ phase: "Deploy", steps: steps as never }];
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "deploy-inputs-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("stepInputRefs", () => {
+  test("a kind's own fields and the template fields, literal paths only", () => {
+    const refs = stepInputRefs("Deploy", { kind: "helm-upgrade", release: "web", chart: "chart", values: ["a.yaml", "@Cfg.values"] } as never);
+    expect(refs.map((r) => [r.field, r.path])).toEqual([["values", "a.yaml"], ["chart", "chart"]]);
+  });
+
+  test("an archive path or a wired value is a build output and is not named", () => {
+    expect(stepInputRefs("Deploy", { kind: "cfn-deploy", template: "archive:stack.json" } as never)).toEqual([]);
+    expect(stepInputRefs("Deploy", { kind: "s3-sync", from: "@Build.dir", to: "s3://b" } as never)).toEqual([]);
+  });
+
+  test("a Docker build's Dockerfile is named under its context", () => {
+    const refs = stepInputRefs("Build", { kind: "docker-build", context: "app", dockerfile: "Dockerfile.prod" } as never);
+    expect(refs.map((r) => r.path)).toEqual(["app", "app/Dockerfile.prod"]);
+  });
+});
+
+describe("componentDeployInputs", () => {
+  test("a file by its bytes, a directory by its files; a missing path is left out", () => {
+    write("values.yaml", "a: 1\n");
+    write("chart/Chart.yaml", "name: c\n");
+    const read = componentDeployInputs(deploy({ kind: "helm-upgrade", chart: "chart", values: ["values.yaml", "gone.yaml"] }), root);
+    expect(read.inputs.map((i) => i.path)).toEqual(["chart", "values.yaml"]);
+    expect(read.inputs.find((i) => i.path === "values.yaml")?.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(read.unbound).toEqual([]);
+  });
+
+  test("a directory's digest moves with a file's bytes, a new file and a renamed one", () => {
+    write("site/index.html", "<h1>a</h1>");
+    const before = directoryDigest(root, "site");
+    write("site/index.html", "<h1>b</h1>");
+    const edited = directoryDigest(root, "site");
+    expect(edited).not.toBe(before);
+    write("site/about.html", "x");
+    expect(directoryDigest(root, "site")).not.toBe(edited);
+  });
+
+  test("the same files under another parent hash the same: the digest reads paths from the directory", () => {
+    write("a/chart/Chart.yaml", "name: c\n");
+    write("b/chart/Chart.yaml", "name: c\n");
+    expect(directoryDigest(root, "a/chart")).toBe(directoryDigest(root, "b/chart"));
+  });
+
+  test("in a git repository, a directory leaves out what git ignores, and a directory git ignores is a build output", () => {
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    write(".gitignore", "node_modules/\ndist/\n");
+    write("app/server.js", "1");
+    write("app/node_modules/dep/index.js", "1");
+    write("dist/index.html", "1");
+    expect(directoryFiles(root, "app")).toEqual(["app/server.js"]);
+    const read = componentDeployInputs(deploy({ kind: "docker-build", context: "app" }, { kind: "s3-sync", from: "dist", to: "s3://b" }), root);
+    expect(read.inputs.map((i) => i.path)).toEqual(["app"]);
+    expect(read.unbound).toEqual([{ phase: "Deploy", kind: "s3-sync", reason: expect.stringMatching(/"dist" is a directory git ignores, so a build output/) }]);
+  });
+
+  test("a file git ignores is still hashed when a step names it, as a template chant build writes", () => {
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    write(".gitignore", "dist/\n");
+    write("dist/stack.json", "{}");
+    expect(componentDeployInputs(deploy({ kind: "cfn-deploy", template: "dist/stack.json" }), root).inputs.map((i) => i.path)).toEqual(["dist/stack.json"]);
+  });
+
+  test("a shell step is unbound; `include` limits the steps read", () => {
+    write("chart/Chart.yaml", "x");
+    const phases = deploy({ kind: "shell", cmd: "./go.sh", reason: "t" }, { kind: "helm-upgrade", chart: "chart" });
+    expect(componentDeployInputs(phases, root).unbound.map((u) => u.kind)).toEqual(["shell"]);
+    expect(componentDeployInputs(phases, root, (s) => s.kind !== "helm-upgrade").inputs).toEqual([]);
+  });
+});
+
+describe("componentPlanDigest with inputs", () => {
+  const component: DriverComponent = { name: "web", dependsOn: [], deploy: deploy({ kind: "helm-upgrade", chart: "chart" }) };
+
+  test("no inputs keeps the digest a composition had before #4155", () => {
+    expect(componentPlanDigest({ environment: "prod", component, inputs: [] })).toBe(componentPlanDigest({ environment: "prod", component }));
+  });
+
+  test("an input's digest moves the plan digest", () => {
+    const a = componentPlanDigest({ environment: "prod", component, inputs: [{ path: "chart", digest: "sha256:aa" }] });
+    const b = componentPlanDigest({ environment: "prod", component, inputs: [{ path: "chart", digest: "sha256:bb" }] });
+    expect(a).not.toBe(b);
+  });
+});

package/src/components/deploy-inputs.ts

@@ -0,0 +1,225 @@
+/**
+ * The local files a component's steps deploy from, and their content digests
+ * (#4155).
+ *
+ * A component gate approves `componentPlanDigest` (./gate-plan.ts). A step
+ * whose capability has a `plan` is bound by what it plans. Every other step
+ * was bound only by its input as written, so a Helm chart, a kustomize
+ * directory or a static site's tree could change after review without moving
+ * the digest. This module names those files and hashes them, so the digest
+ * moves when they do.
+ *
+ * Which fields name a path is data, as the template fields are in
+ * ./release-compile.ts and the unit fields in ./deploy-units.ts: a kind's
+ * fields in {@link DEPLOY_INPUT_FIELDS}, plus `template`, `manifest` and
+ * `values` on any step ({@link TEMPLATE_FIELDS}). Only a literal path counts:
+ * a value wired from another step (`@Build.uri`) or an `archive:` path is a
+ * build output, and binding it would make an approval unusable by a build
+ * that is not reproducible. The build steps' own sources are bound instead.
+ *
+ * - A file is hashed by its bytes.
+ * - A directory is hashed over the files under it that git does not ignore
+ *   (`git ls-files --cached --others --exclude-standard`), each by its path
+ *   and bytes, so `node_modules` and a build's `dist` inside a Docker context
+ *   are left out. Outside a git repository every file is hashed except under
+ *   `.git` and `node_modules`.
+ * - A directory git ignores as a whole is a build output. It is not hashed;
+ *   the step is listed as unbound, with that reason.
+ * - A path that does not exist is left out. One that appears later moves the
+ *   digest.
+ *
+ * A step whose kind runs content chant can't name, such as `shell`, is listed
+ * as unbound ({@link UNBOUND_KINDS}), so the plan note can show a reviewer
+ * what the approval does not cover.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { sha256Hex } from "../content-digest";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DriverGate, DriverPhase, DriverStep } from "./driver";
+
+/** The fields that name every step's deployed file, whatever its kind (as ./release-compile.ts reads them). */
+export const TEMPLATE_FIELDS: readonly string[] = ["template", "manifest", "values"];
+
+/** Per kind, the fields beyond {@link TEMPLATE_FIELDS} that name a local file or directory the step deploys or builds from. */
+export const DEPLOY_INPUT_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  "helm-upgrade": ["chart"],
+  "kustomize-apply": ["dir"],
+  "fly-release": ["plan"],
+  "fly-rollback": ["plan"],
+  "s3-sync": ["from"],
+  "r2-sync": ["from"],
+  "copy-to-host": ["from"],
+  "wrangler-deploy": ["config"],
+  "wrangler-versions-promote": ["config"],
+  "docker-build": ["context"],
+  "zip-package": ["source"],
+  "jvm-build": ["path"],
+};
+
+/** Kinds that deploy content chant can't name from their input: a command, an agent's work. */
+export const UNBOUND_KINDS: readonly string[] = ["shell", "run-agent"];
+
+/** One path a step names. */
+export interface DeployInputRef {
+  phase: string;
+  kind: string;
+  field: string;
+  /** Relative to the member's directory, as written. */
+  path: string;
+}
+
+/** A named path and the digest of what is there. */
+export interface DeployInputDigest {
+  path: string;
+  /** `sha256:<hex>` of a file's bytes, or a plan digest over a directory's files. */
+  digest: string;
+}
+
+/** A step the digest does not cover, and why. */
+export interface UnboundStep {
+  phase: string;
+  kind: string;
+  reason: string;
+}
+
+/** What a component's steps deploy from: the digests, and the steps they can't cover. */
+export interface ComponentDeployInputs {
+  inputs: DeployInputDigest[];
+  unbound: UnboundStep[];
+}
+
+function isGate(step: DriverStep | DriverGate | DriverPhase): step is DriverGate {
+  return (step as { kind?: unknown }).kind === "gate";
+}
+
+function isPhase(step: DriverStep | DriverGate | DriverPhase): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+const isLiteralPath = (v: unknown): v is string =>
+  typeof v === "string" && v !== "" && !v.startsWith("@") && !v.startsWith("$") && !v.startsWith("archive:");
+
+/** Every capability step of a composition with its phase, nested phases included, gates left out. */
+export function stepsWithPhase(phases: readonly DriverPhase[]): Array<{ phase: string; step: DriverStep }> {
+  const out: Array<{ phase: string; step: DriverStep }> = [];
+  const walk = (phase: DriverPhase): void => {
+    for (const step of phase.steps) {
+      if (isPhase(step)) walk(step);
+      else if (!isGate(step)) out.push({ phase: phase.phase, step });
+    }
+  };
+  phases.forEach(walk);
+  return out;
+}
+
+/** The literal paths one step names, in field order. A Docker build's Dockerfile is named under its context. */
+export function stepInputRefs(phase: string, step: DriverStep): DeployInputRef[] {
+  const out: DeployInputRef[] = [];
+  for (const field of [...TEMPLATE_FIELDS, ...(DEPLOY_INPUT_FIELDS[step.kind] ?? [])]) {
+    const raw = step[field];
+    for (const value of Array.isArray(raw) ? raw : [raw]) {
+      if (isLiteralPath(value)) out.push({ phase, kind: step.kind, field, path: value });
+    }
+  }
+  if (step.kind === "docker-build" && isLiteralPath(step.context) && isLiteralPath(step.dockerfile)) {
+    out.push({ phase, kind: step.kind, field: "dockerfile", path: join(step.context, step.dockerfile) });
+  }
+  return out;
+}
+
+function git(root: string, args: string[]): { ok: boolean; out: string } {
+  const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 });
+  return { ok: r.status === 0, out: r.stdout ?? "" };
+}
+
+/** The files under `dir` (relative to `root`) a directory digest covers, relative to `root`, sorted. */
+export function directoryFiles(root: string, dir: string): string[] {
+  const listed = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", dir]);
+  if (listed.ok) {
+    return [...new Set(listed.out.split("\0").filter((p) => p !== ""))]
+      .filter((p) => {
+        const full = resolve(root, p);
+        return existsSync(full) && statSync(full).isFile();
+      })
+      .sort();
+  }
+  return walkFiles(root, dir);
+}
+
+/** Every file under `dir`, relative to `root`, sorted, leaving out `.git` and `node_modules`. What a cut records of a directory git ignores. */
+export function walkFiles(root: string, dir: string): string[] {
+  const out: string[] = [];
+  const walk = (abs: string): void => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      const full = join(abs, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(relative(root, full).split(sep).join("/"));
+    }
+  };
+  walk(resolve(root, dir));
+  return out.sort();
+}
+
+/** Whether git ignores `path` (relative to `root`). False outside a git repository. */
+export function ignoredByGit(root: string, path: string): boolean {
+  return git(root, ["check-ignore", "-q", "--", path]).ok;
+}
+
+/** `sha256:<hex>` of a file's bytes. */
+export function fileDigest(file: string): string {
+  return `sha256:${sha256Hex(readFileSync(file))}`;
+}
+
+/** The digest of the files under `dir`: a plan digest over each file's path (from `dir`) and bytes. */
+export function directoryDigest(root: string, dir: string): string {
+  const base = resolve(root, dir);
+  const files = directoryFiles(root, dir).map((p) => ({
+    path: relative(base, resolve(root, p)).split(sep).join("/"),
+    digest: fileDigest(resolve(root, p)),
+  }));
+  return computePlanDigest("directory", files);
+}
+
+/**
+ * What a component's steps deploy from, read under `root` (the member's
+ * directory). `include` picks the steps to read, all of them by default; the
+ * wave planner passes the steps without a `plan`, which their plan does not
+ * already cover.
+ */
+export function componentDeployInputs(
+  phases: readonly DriverPhase[],
+  root: string,
+  include: (step: DriverStep) => boolean = () => true,
+): ComponentDeployInputs {
+  const inputs = new Map<string, string>();
+  const unbound: UnboundStep[] = [];
+  for (const { phase, step } of stepsWithPhase(phases)) {
+    if (!include(step)) continue;
+    if (UNBOUND_KINDS.includes(step.kind)) {
+      unbound.push({ phase, kind: step.kind, reason: `a ${step.kind} step runs content chant can't name from its input` });
+      continue;
+    }
+    for (const ref of stepInputRefs(phase, step)) {
+      if (inputs.has(ref.path)) continue;
+      const full = resolve(root, ref.path);
+      if (!existsSync(full)) continue;
+      if (statSync(full).isDirectory()) {
+        if (ignoredByGit(root, ref.path)) {
+          unbound.push({ phase, kind: step.kind, reason: `its ${ref.field} "${ref.path}" is a directory git ignores, so a build output; bind its sources through the step that builds it` });
+          continue;
+        }
+        inputs.set(ref.path, directoryDigest(root, ref.path));
+      } else {
+        inputs.set(ref.path, fileDigest(full));
+      }
+    }
+  }
+  return {
+    inputs: [...inputs].map(([path, digest]) => ({ path, digest })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    unbound,
+  };
+}

package/src/components/driver.ts

@@ -52,6 +52,7 @@ import { evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedg
 import { gateName } from "../op/gate-name";
 import { GateNotRecordableError } from "../lifecycle/no-record";
 import { componentPlanDigest } from "./gate-plan";
+import { componentDeployInputs } from "./deploy-inputs";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
 import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
@@ -853,6 +854,13 @@ async function rollbackExecuted(
 
 // ── Per-component deploy ─────────────────────────────────────────────────
 
+/** Whether a component's composition has a gate step anywhere, nested phases and `rollback` included. */
+function hasGateStep(component: DriverComponent): boolean {
+  const walk = (steps: DriverPhase["steps"]): boolean =>
+    steps.some((step) => isGateStep(step) || (Array.isArray((step as DriverPhase).steps) && walk((step as DriverPhase).steps)));
+  return [...component.deploy, ...(component.rollback ?? [])].some((p) => walk(p.steps));
+}
+
 /**
  * Run one component's `deploy` composition. On terminal failure: unwind every
  * executed step in reverse via its capability's `rollback` (saga
@@ -900,6 +908,9 @@ export async function runComponentDeploy(
         component,
         ...(ctx.vars ? { vars: ctx.vars } : {}),
         ...(release !== undefined ? { release } : {}),
+        // #4155: the files the steps deploy from, read where the steps read
+        // them. Only a gate reads the digest, so a run with none skips the hashing.
+        ...(hasGateStep(component) ? { inputs: componentDeployInputs(component.deploy, process.cwd()).inputs } : {}),
       }),
   };
   const records: DriverStepRecord[] = [];

package/src/components/gate-plan.ts

@@ -17,6 +17,11 @@
  *   its publish output against a recorded digest that is not in the
  *   composition, so it passes that digest here.
  * - `vars`, the environment config the caller resolved ahead of the run.
+ * - The content digests of the local files the steps deploy from (#4155,
+ *   ./deploy-inputs.ts): a chart, a manifest, a site's tree, a build step's
+ *   sources. A file changed after review moves the digest. The key is left
+ *   out when no step names an existing file, so a composition that deploys
+ *   none keeps the digest it had before #4155.
  *
  * ## What it leaves out
  *
@@ -28,6 +33,7 @@
  */
 
 import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DeployInputDigest } from "./deploy-inputs";
 import type { DriverComponent } from "./driver";
 
 /** What a component gate's plan digest is taken over. */
@@ -37,6 +43,8 @@ export interface ComponentGatePlan {
   vars?: Record<string, unknown>;
   /** The recorded digest a promote or rollback deploys, when the caller has one. */
   release?: string;
+  /** What the steps deploy from (`componentDeployInputs`), when the caller read it. */
+  inputs?: readonly DeployInputDigest[];
 }
 
 /** The plan digest a component gate records and approves. */
@@ -49,5 +57,6 @@ export function componentPlanDigest(plan: ComponentGatePlan): string {
     rollback: component.rollback ?? null,
     vars: plan.vars ?? null,
     release: plan.release ?? null,
+    ...(plan.inputs && plan.inputs.length > 0 ? { inputs: plan.inputs } : {}),
   });
 }

package/src/components/pr-pipeline.ts

@@ -1,6 +1,7 @@
 /**
  * The jobs of a generated pull-request pipeline (#3183): a plan job on every
- * pull request and an apply job on every push to the target branch.
+ * pull request and, on every push to the target branch, a record job, or an
+ * apply job when the pipeline opts into apply on merge (#4168).
  *
  * Each forge's generator (the github, gitlab and forgejo lexicons) adds its
  * own triggers, permissions and artifact handling; the commands and the
@@ -9,11 +10,19 @@
  * - The plan job runs `chant components pr-plan` against the pull request's
  *   target commit. It posts the note and the `chant/plan` status and writes
  *   nothing to `chant/lifecycle`, since it runs the pull request's code.
- * - The apply job runs `chant components pr-apply` against the commit the
+ * - The record job (#4168 step 1, the default) runs `chant components
+ *   pr-record` against the commit the push replaced. It plans the same
+ *   members on the merged commit, stores the change set and writes the merge
+ *   record, `_merges/<commit>.json` on `chant/lifecycle`. It applies nothing:
+ *   a release that carries the commit deploys it. It needs write access to
+ *   `chant/lifecycle`. One record runs at a time per environment.
+ * - With `applyOnMerge` the apply job takes the record job's place. It runs
+ *   `chant components pr-apply` against the commit the
  *   push replaced, finds the pull request that merged the pushed commit
  *   through the forge, and applies only when an approval stands for the
- *   digest it plans. With `requireReview` (the default) the approver must
- *   also have approved the pull request on the forge. It needs write access
+ *   digest it plans. With `requireReview` (off by default since #4168, on
+ *   under the `review-rules` security group) the approver must also have
+ *   approved the pull request on the forge. It needs write access
  *   to `chant/lifecycle`, to record the pending fact when the gate stops it.
  *   One apply runs at a time per environment.
  *
@@ -35,6 +44,7 @@
  * it too. With `reportUrl` both pass `--report-url`, which copies the report,
  * the change set and the events where a reader outside CI can fetch them;
  * the job's own environment brings the credentials an `s3://` URL needs.
+ * The record job passes the same flags as the apply.
  *
  * With `build` (#4088) both jobs run the project's build and `chant lint`
  * before their command, and fail on an error. A `cfn-deploy` member's plan
@@ -123,8 +133,16 @@ export interface PrLoopPipelineOptions {
    * GitHub and Forgejo; on GitLab, the project's default branch.
    */
   branch?: string;
-  /** Count an approval only from someone who approved the pull request on the forge. Default true. */
+  /** Count an approval only from someone who approved the pull request on the forge. Default false (#4168): review rules are opt-in. */
   requireReview?: boolean;
+  /** The job on merge (apply, or record since #4168) has `chant ci run` refuse to start without a runner-start statement for it (`--require-runner-start`, #4147), as under the `isolated-runners` security group (#4168). Default false. */
+  requireRunnerStart?: boolean;
+  /**
+   * Apply the approved plan on merge (#4168), as every pull-request pipeline
+   * did before #4168: the apply job in place of the record job. Default
+   * false, so a merge deploys nothing. `waveGate` needs it.
+   */
+  applyOnMerge?: boolean;
   /**
    * Stream each job's run events (#4007): `--events-json` on both commands,
    * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
@@ -166,8 +184,8 @@ export interface PrLoopPipelineOptions {
 
 /** One job's command and the forge values it reads, as environment variables for its step. */
 export interface PrLoopJob {
-  /** `plan` or `apply`. */
-  jobName: "plan" | "apply";
+  /** `plan`, `apply` or `record` (#4168). */
+  jobName: "plan" | "apply" | "record";
   /** The command line. Reads `$BASE_SHA` and, for the plan, `$PR_NUMBER`. */
   command: string;
   /**
@@ -200,9 +218,10 @@ export function prLoopBuildLines(env: string, options: PrLoopPipelineOptions = {
 }
 
 /**
- * The two jobs for `forge`. `member` is the workspace member the pipeline is
- * generated for; the commands then run in its directory, so `--output` is
- * relative to it.
+ * The jobs for `forge`: plan, apply and record, in that order. A generator
+ * writes the plan and, on merge, {@link prLoopMergeJob}'s choice of the
+ * other two. `member` is the workspace member the pipeline is generated for;
+ * the commands then run in its directory, so `--output` is relative to it.
  */
 export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}, member?: string): PrLoopJob[] {
   const gate = options.gate ?? PR_APPLY_GATE;
@@ -220,13 +239,14 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
     ...(options.events ? { CHANT_RUN_EVENTS_DIR: PR_LOOP_EVENTS_DIR } : {}),
   };
   // #4156: the flags `chant ci run` rebuilds `command` from. It finds the member from the directory it runs in.
-  const ciRun = (job: "plan" | "apply"): string[] => [
+  const ciRun = (job: PrLoopJob["jobName"]): string[] => [
     "chant", "ci", "run", job, "--in-place", ...(job === "plan" ? ["--no-push"] : []),
     "--base", '"$BASE_SHA"', ...(job === "plan" ? ["--pr", '"$PR_NUMBER"'] : []),
     "--env", env, "--gate", gate, "--forge", forge,
-    ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
-    ...(job === "apply" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
-    ...(job === "apply" && options.requireReview === false ? ["--no-require-review"] : []),
+    ...(job !== "record" && options.waveGate ? ["--wave-gate", options.waveGate] : []),
+    ...(job !== "plan" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
+    ...(job === "apply" && options.requireReview === true ? ["--require-review"] : []),
+    ...(job !== "plan" && options.requireRunnerStart === true ? ["--require-runner-start"] : []),
     ...(options.events ? ["--events-json"] : []),
     ...(options.reportUrl ? ["--report-url", JSON.stringify(options.reportUrl)] : []),
   ];
@@ -248,7 +268,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       jobName: "apply",
       command: [
         "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
-        ...(options.requireReview === false ? [] : ["--require-review"]),
+        ...(options.requireReview === true ? ["--require-review"] : []),
         ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
         "--resume", PR_APPLY_RECORD,
       ].join(" "),
@@ -257,9 +277,22 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       ...build,
       run: { command: ciRun("apply").join(" "), env: runEnv(applyEnv) },
     },
+    {
+      jobName: "record",
+      command: ["chant", "components", "pr-record", "--base", '"$BASE_SHA"', ...common].join(" "),
+      env: applyEnv,
+      setup: [github ? githubBaseFallback(options.branch) : gitlabBaseFallback(options.branch)],
+      ...build,
+      run: { command: ciRun("record").join(" "), env: runEnv(applyEnv) },
+    },
   ];
 }
 
+/** The job a push to the target branch runs (#4168): `record`, or `apply` when the pipeline opts into apply on merge. */
+export function prLoopMergeJob(jobs: readonly PrLoopJob[], options: PrLoopPipelineOptions = {}): PrLoopJob {
+  return jobs.find((j) => j.jobName === (options.applyOnMerge ? "apply" : "record"))!;
+}
+
 /**
  * The pull-request options with `--wave-gate` beside `--pr-loop` (#4003):
  * the apply gets a gate per wave. A canary or a fixed base is refused, since
@@ -268,6 +301,9 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
  */
 export function prLoopWithWaves(prLoop: PrLoopPipelineOptions, gatedWaves?: GatedWavePipelineOptions): PrLoopPipelineOptions {
   if (!gatedWaves) return prLoop;
+  if (!prLoop.applyOnMerge) {
+    throw new Error("--wave-gate beside --pr-loop gates the apply on merge, so it needs --apply-on-merge (#4168); without it a merge records the plan and a release deploys it");
+  }
   if (gatedWaves.canary?.length) throw new Error("a pull-request pipeline's waves are the change's derivation, so it takes no --canary; drop --canary");
   if (gatedWaves.base !== undefined) throw new Error("a pull-request pipeline measures each push from the commit before it, so it takes no --base; drop --base");
   return { ...prLoop, waveGate: gatedWaves.gate };
@@ -310,6 +346,11 @@ export function prApplyGroup(env: string, member?: string): string {
   return member ? `chant-apply.${member}.${env}` : `chant-apply-${env}`;
 }
 
+/** The group that keeps one record job at a time per environment and member (#4168), named as {@link prApplyGroup} names the apply's. */
+export function prRecordGroup(env: string, member?: string): string {
+  return member ? `chant-record.${member}.${env}` : `chant-record-${env}`;
+}
+
 /**
  * The cache key the apply job keeps its attempt record under (#3543), with
  * `commit` the forge's expression for the pushed commit. A push of another

package/src/components/pr-run.ts

@@ -737,7 +737,7 @@ export function waveNotCovered(approved: ChangeSetDocument, fresh: ChangeSetDocu
 }
 
 export interface PrReportInput {
-  stage: "plan" | "apply";
+  stage: "plan" | "apply" | "record";
   pr: number | null;
   env: string;
   /** The workspace member whose pipeline runs the stage (#3465). */