@intentius/chant-lexicon-github 0.124.31 → 0.124.32

package/dist/variables.js

@@ -0,0 +1,41 @@
+/**
+ * GitHub Actions predefined context variable references.
+ *
+ * These provide type-safe access to GitHub and Runner context values
+ * that expand to `${{ context.property }}` expressions in YAML.
+ */
+import { Expression } from "./expression.js";
+export const GitHub = {
+    Ref: /* @__PURE__ */ new Expression("github.ref"),
+    RefName: /* @__PURE__ */ new Expression("github.ref_name"),
+    RefType: /* @__PURE__ */ new Expression("github.ref_type"),
+    Sha: /* @__PURE__ */ new Expression("github.sha"),
+    Actor: /* @__PURE__ */ new Expression("github.actor"),
+    TriggeringActor: /* @__PURE__ */ new Expression("github.triggering_actor"),
+    Repository: /* @__PURE__ */ new Expression("github.repository"),
+    RepositoryOwner: /* @__PURE__ */ new Expression("github.repository_owner"),
+    EventName: /* @__PURE__ */ new Expression("github.event_name"),
+    Event: /* @__PURE__ */ new Expression("github.event"),
+    RunId: /* @__PURE__ */ new Expression("github.run_id"),
+    RunNumber: /* @__PURE__ */ new Expression("github.run_number"),
+    RunAttempt: /* @__PURE__ */ new Expression("github.run_attempt"),
+    Workflow: /* @__PURE__ */ new Expression("github.workflow"),
+    WorkflowRef: /* @__PURE__ */ new Expression("github.workflow_ref"),
+    Workspace: /* @__PURE__ */ new Expression("github.workspace"),
+    Token: /* @__PURE__ */ new Expression("github.token"),
+    Job: /* @__PURE__ */ new Expression("github.job"),
+    HeadRef: /* @__PURE__ */ new Expression("github.head_ref"),
+    BaseRef: /* @__PURE__ */ new Expression("github.base_ref"),
+    ServerUrl: /* @__PURE__ */ new Expression("github.server_url"),
+    ApiUrl: /* @__PURE__ */ new Expression("github.api_url"),
+    GraphqlUrl: /* @__PURE__ */ new Expression("github.graphql_url"),
+    Action: /* @__PURE__ */ new Expression("github.action"),
+    ActionPath: /* @__PURE__ */ new Expression("github.action_path"),
+};
+export const Runner = {
+    Os: /* @__PURE__ */ new Expression("runner.os"),
+    Arch: /* @__PURE__ */ new Expression("runner.arch"),
+    Name: /* @__PURE__ */ new Expression("runner.name"),
+    Temp: /* @__PURE__ */ new Expression("runner.temp"),
+    ToolCache: /* @__PURE__ */ new Expression("runner.tool_cache"),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.124.31",
+  "version": "0.124.32",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -32,17 +32,17 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -54,13 +54,13 @@
     "validate": "tsx src/validate-cli.ts",
     "docs": "tsx src/codegen/docs-cli.ts",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json"
   },
   "devDependencies": {
     "@intentius/chant": "*",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.31"
+    "@intentius/chant": "^0.124.32"
   }
 }

package/src/codegen/package.ts

@@ -5,7 +5,7 @@
 import { readFileSync } from "fs";
 import { githubPlugin } from "../plugin";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { IntrinsicDef } from "@intentius/chant/lexicon";
 import {
   packagePipeline,
@@ -17,7 +17,7 @@ import { generate } from "./generate";
 
 export type { PackageOptions, PackageResult };
 
-const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
 
 /**
  * Package the GitHub Actions lexicon into a distributable BundleSpec.

package/src/components/__fixtures__/pr-loop-build.github.golden.yml

@@ -34,7 +34,8 @@ jobs:
           BASE_SHA: '${{ github.event.pull_request.base.sha }}'
           PR_NUMBER: '${{ github.event.pull_request.number }}'
           GITHUB_TOKEN: '${{ github.token }}'
-        run: chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github
       - name: Keep the plan report
         if: always()
         uses: actions/upload-artifact@v4
@@ -73,7 +74,10 @@ jobs:
         env:
           BASE_SHA: '${{ github.event.before }}'
           GITHUB_TOKEN: '${{ github.token }}'
-        run: chant components pr-apply --base "$BASE_SHA" --env prod --gate pr-apply --output .chant/pr --forge github --require-review --resume .chant/pr-resume/pr-apply.json
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then git fetch origin "main" && BASE_SHA="$(git merge-base FETCH_HEAD "$GITHUB_SHA")"; if [ "$BASE_SHA" = "$GITHUB_SHA" ]; then BASE_SHA="$(git rev-parse --verify --quiet "$GITHUB_SHA^" || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"; fi; fi; export BASE_SHA
+          chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github
       - name: Keep the record for a re-run
         if: always()
         uses: actions/cache/save@v4

package/src/components/__fixtures__/pr-loop-waves.github.golden.yml

@@ -0,0 +1,178 @@
+name: chant-pr-prod
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+env:
+  CHANT_ENV: prod
+
+jobs:
+  plan:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    container: node:22
+    permissions:
+      contents: read
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Plan the members this pull request reaches
+        env:
+          BASE_SHA: '${{ github.event.pull_request.base.sha }}'
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github --wave-gate release
+      - name: Keep the plan report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chant-pr-plan
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true
+  apply-wave-1:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    container: node:22
+    concurrency:
+      group: chant-apply-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Restore the newest record of this commit's apply
+        uses: actions/cache/restore@v4
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}-wave-1
+          restore-keys: chant-apply-prod-${{ github.sha }}-
+      - name: Apply wave 1, under the approval its plan has
+        env:
+          BASE_SHA: '${{ github.event.before }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then git fetch origin "main" && BASE_SHA="$(git merge-base FETCH_HEAD "$GITHUB_SHA")"; if [ "$BASE_SHA" = "$GITHUB_SHA" ]; then BASE_SHA="$(git rev-parse --verify --quiet "$GITHUB_SHA^" || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"; fi; fi; export BASE_SHA
+          chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github --wave-gate release --wave 1
+      - name: Keep the record for the next wave and a re-run
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}-wave-1
+      - name: Keep the wave 1 apply report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chant-pr-apply-wave-1
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true
+  apply-wave-2:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs:
+      - apply-wave-1
+    container: node:22
+    concurrency:
+      group: chant-apply-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Restore the newest record of this commit's apply
+        uses: actions/cache/restore@v4
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}-wave-2
+          restore-keys: chant-apply-prod-${{ github.sha }}-
+      - name: Apply wave 2, under the approval its plan has
+        env:
+          BASE_SHA: '${{ github.event.before }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then git fetch origin "main" && BASE_SHA="$(git merge-base FETCH_HEAD "$GITHUB_SHA")"; if [ "$BASE_SHA" = "$GITHUB_SHA" ]; then BASE_SHA="$(git rev-parse --verify --quiet "$GITHUB_SHA^" || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"; fi; fi; export BASE_SHA
+          chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github --wave-gate release --wave 2
+      - name: Keep the record for the next wave and a re-run
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}-wave-2
+      - name: Keep the wave 2 apply report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chant-pr-apply-wave-2
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true
+  apply-wave-3:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs:
+      - apply-wave-2
+    container: node:22
+    concurrency:
+      group: chant-apply-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Restore the newest record of this commit's apply
+        uses: actions/cache/restore@v4
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}-wave-3
+          restore-keys: chant-apply-prod-${{ github.sha }}-
+      - name: Apply wave 3, under the approval its plan has
+        env:
+          BASE_SHA: '${{ github.event.before }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then git fetch origin "main" && BASE_SHA="$(git merge-base FETCH_HEAD "$GITHUB_SHA")"; if [ "$BASE_SHA" = "$GITHUB_SHA" ]; then BASE_SHA="$(git rev-parse --verify --quiet "$GITHUB_SHA^" || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"; fi; fi; export BASE_SHA
+          chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github --wave-gate release --wave 3
+      - name: Keep the record for the next wave and a re-run
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}-wave-3
+      - name: Keep the wave 3 apply report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chant-pr-apply-wave-3
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true

package/src/components/__fixtures__/pr-loop.github.golden.yml

@@ -30,7 +30,8 @@ jobs:
           BASE_SHA: '${{ github.event.pull_request.base.sha }}'
           PR_NUMBER: '${{ github.event.pull_request.number }}'
           GITHUB_TOKEN: '${{ github.token }}'
-        run: chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github
       - name: Keep the plan report
         if: always()
         uses: actions/upload-artifact@v4
@@ -65,7 +66,10 @@ jobs:
         env:
           BASE_SHA: '${{ github.event.before }}'
           GITHUB_TOKEN: '${{ github.token }}'
-        run: chant components pr-apply --base "$BASE_SHA" --env prod --gate pr-apply --output .chant/pr --forge github --require-review --resume .chant/pr-resume/pr-apply.json
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then git fetch origin "main" && BASE_SHA="$(git merge-base FETCH_HEAD "$GITHUB_SHA")"; if [ "$BASE_SHA" = "$GITHUB_SHA" ]; then BASE_SHA="$(git rev-parse --verify --quiet "$GITHUB_SHA^" || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"; fi; fi; export BASE_SHA
+          chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github
       - name: Keep the record for a re-run
         if: always()
         uses: actions/cache/save@v4

package/src/components/generate-pipeline.ts

@@ -60,7 +60,17 @@ import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/co
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
 import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
 import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
-import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prLoopJobs, prLoopSetup } from "@intentius/chant/components/pr-pipeline";
+import {
+  PR_APPLY_RECORD,
+  PR_LOOP_REPORT_DIR,
+  prApplyGroup,
+  prApplyRecordKey,
+  prApplyWaveJobName,
+  prLoopJobs,
+  prLoopSetup,
+  prLoopWaveJobs,
+  prLoopWithWaves,
+} from "@intentius/chant/components/pr-pipeline";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -175,8 +185,17 @@ function gatedWaveGithubDoc(
  * path filter, since a change outside the member can reach it; the plan
  * selects from the whole change and passes `--member`, which keeps the
  * member's gate, note and statuses apart from the other members'.
+ *
+ * With a gate per wave (`waveGate`, #4003) the one apply job becomes
+ * `apply-wave-1` to `apply-wave-<n>`, one per wave of the component graph,
+ * each needing the one before. Each saves the record under its own cache key
+ * (the run, the attempt and the wave), and each restores the newest record
+ * for the pushed commit, so wave k reads what wave k-1 left, and a re-run of
+ * a wave that stopped at its gate reads what it left itself. Each keeps its
+ * report as `chant-pr-apply-wave-<k>`.
  */
 function prLoopGithubDoc(
+  components: DriverComponent[],
   env: string,
   image: string,
   beforeScript: string[],
@@ -194,34 +213,53 @@ function prLoopGithubDoc(
   // its run and attempt, and a re-run restores the newest for the commit.
   const recordPath = member ? memberRepoPath(member, PR_APPLY_RECORD) : PR_APPLY_RECORD;
   const recordPrefix = `${prApplyRecordKey(env, "${{ github.sha }}", member?.name)}-`;
-  const recordKey = `${recordPrefix}\${{ github.run_id }}-\${{ github.run_attempt }}`;
-  const restoreRecord = {
-    name: "Restore the record of an earlier attempt at this commit",
+  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",
-    with: { path: recordPath, key: recordKey, "restore-keys": recordPrefix },
-  };
-  const saveRecord = {
-    name: "Keep the record for a re-run",
+    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",
-    with: { path: recordPath, key: recordKey },
-  };
+    with: { path: recordPath, key: recordKey(wave) },
+  });
+  const reportName = (job: typeof plan) => `chant-pr-${job.wave ? prApplyWaveJobName(job.wave) : job.jobName}`;
   const steps = (job: typeof plan, name: string): Array<Record<string, unknown>> => [
     checkoutStep(true),
     ...runSteps(prLoopSetup(image)),
     ...runSteps(beforeScript),
     ...(job.build ? [{ name: "Build the templates", run: job.build[0] }, { name: "Lint the project", run: job.build[1] }] : []),
-    ...(job.jobName === "apply" ? [restoreRecord] : []),
-    { name, env: job.env, run: job.command },
+    ...(job.jobName === "apply" ? [restoreRecord(job.wave)] : []),
+    // The job's setup lines (#4004) run in the command's shell, so a value they settle reaches it.
+    // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY secret is set.
+    { name, env: job.run.env, run: [...(job.setup ?? []), job.run.command].join("\n") },
     ...runSteps(extraScript),
-    ...(job.jobName === "apply" ? [saveRecord] : []),
+    ...(job.jobName === "apply" ? [saveRecord(job.wave)] : []),
     {
-      name: `Keep the ${job.jobName} report`,
+      name: `Keep the ${job.wave ? `wave ${job.wave} ` : ""}${job.jobName} report`,
       if: "always()",
       uses: UPLOAD_ARTIFACT,
-      with: { name: `chant-pr-${job.jobName}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true },
+      with: { name: reportName(job), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true },
     },
   ];
+  const applyJob = (job: typeof plan, needs: string[], name: string) => ({
+    if: "github.event_name == 'push'",
+    "runs-on": GITHUB_RUNNER,
+    ...(needs.length > 0 ? { needs } : {}),
+    container: image,
+    concurrency: concurrency(prApplyGroup(env, member?.name)),
+    permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
+    steps: steps(job, name),
+  });
+  const waveJobs = loop.waveGate ? prLoopWaveJobs(components, apply) : [];
+  const applyJobs: Array<[string, Record<string, unknown>]> = loop.waveGate
+    ? waveJobs.map((job) => [
+        prApplyWaveJobName(job.wave!),
+        applyJob(job, job.wave! > 1 ? [prApplyWaveJobName(job.wave! - 1)] : [], `Apply wave ${job.wave}, under the approval its plan has`),
+      ])
+    : [["apply", applyJob(apply, [], "Apply the plan a reviewer approved")]];
   const jobsDoc: Record<string, unknown> = {
     plan: {
       if: "github.event_name == 'pull_request'",
@@ -230,15 +268,9 @@ function prLoopGithubDoc(
       permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
       steps: steps(plan, "Plan the members this pull request reaches"),
     },
-    apply: {
-      if: "github.event_name == 'push'",
-      "runs-on": GITHUB_RUNNER,
-      container: image,
-      concurrency: concurrency(prApplyGroup(env, member?.name)),
-      permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
-      steps: steps(apply, "Apply the plan a reviewer approved"),
-    },
+    ...Object.fromEntries(applyJobs),
   };
+  const applyNames = applyJobs.map(([name]) => name);
   return {
     name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
     environment: env,
@@ -246,10 +278,15 @@ function prLoopGithubDoc(
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", "apply"],
+    stages: ["plan", ...applyNames],
     jobs: [
       { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
-      { jobName: "apply", component: "pull request apply", stage: "apply", needs: [] },
+      ...applyNames.map((name, i) => ({
+        jobName: name,
+        component: loop.waveGate ? `pull request apply, wave ${i + 1}` : "pull request apply",
+        stage: name,
+        needs: i > 0 ? [applyNames[i - 1]] : [],
+      })),
     ],
   };
 }
@@ -315,10 +352,10 @@ export function buildGithubPipelineDoc(
   const byName = new Map(components.map((c) => [c.name, c]));
 
   if (options.prLoop) {
-    if (options.gatedWaves || options.promoteTo !== undefined) {
-      throw new Error("a pull-request pipeline has no wave or promote jobs; drop --wave-gate and --promote-to, or --pr-loop");
-    }
-    return prLoopGithubDoc(env, image, beforeScript, extraScript, options);
+    if (options.promoteTo !== undefined) throw new Error("a pull-request pipeline has no promote job; drop --promote-to or --pr-loop");
+    // #4003: --wave-gate beside --pr-loop gives the apply a gate per wave.
+    const prLoop = prLoopWithWaves(options.prLoop, options.gatedWaves);
+    return prLoopGithubDoc(components, env, image, beforeScript, extraScript, { ...options, prLoop });
   }
 
   if (options.gatedWaves) {

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

@@ -11,7 +11,7 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { parseYAML } from "@intentius/chant/yaml";
 import type { DriverComponent } from "@intentius/chant/components/driver";
-import { prApplyGroup, prApplyRecordKey } from "@intentius/chant/components/pr-pipeline";
+import { githubBaseFallback, prApplyGroup, prApplyRecordKey, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
 import { generateGithubPipeline } from "./generate-pipeline";
 
 const ESTATE: DriverComponent[] = [
@@ -63,28 +63,49 @@ describe("the GitHub pull-request workflow", () => {
   });
 
   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("pr-plan"))!;
-    expect(plan.run).toBe('chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github');
+    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(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" });
 
-    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("pr-apply"))!;
-    expect(apply.run).toContain("--require-review");
-    expect(apply.env).toMatchObject({ BASE_SHA: "${{ github.event.before }}" });
+    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
+    // ci run builds pr-apply with --require-review unless told --no-require-review.
+    expect(apply.run).not.toContain("--no-require-review");
+    expect(apply.run).not.toContain("--no-push");
+    expect(apply.env).toMatchObject({ BASE_SHA: "${{ github.event.before }}", 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 });
   });
 
+  test("a first push's all-zero github.event.before is settled in the apply's own shell, before pr-apply reads it (#4004)", () => {
+    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
+    const lines = apply.run!.trimEnd().split("\n");
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toBe(githubBaseFallback());
+    expect(lines[0]).toContain('[ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]');
+    expect(lines[0]).toContain('git merge-base FETCH_HEAD "$GITHUB_SHA"');
+    expect(lines[1]).toMatch(/^chant ci run apply --in-place --base "\$BASE_SHA"/);
+    const trunk = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { branch: "trunk" } }).yaml) as { jobs: Record<string, Job> };
+    expect(trunk.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!.run).toContain('git fetch origin "trunk"');
+    const plan = doc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!;
+    expect(plan.run).not.toContain("0000000000000000000000000000000000000000");
+  });
+
   test("the apply resumes from a record the cache keeps for the pushed commit across a re-run (#3543)", () => {
     const steps = doc.jobs.apply.steps;
     const restore = steps.findIndex((s) => s.uses === "actions/cache/restore@v4");
-    const run = steps.findIndex((s) => s.run?.includes("pr-apply"));
+    const run = steps.findIndex((s) => s.run?.includes("ci run apply"));
     const save = steps.findIndex((s) => s.uses === "actions/cache/save@v4");
     expect(restore).toBeGreaterThan(-1);
     expect(restore).toBeLessThan(run);
     expect(save).toBeGreaterThan(run);
-    expect(steps[run].run).toContain("--resume .chant/pr-resume/pr-apply.json");
+    // ci run runs the inner pr-apply in the checkout, where the cache restored the record.
+    expect(steps[run].run).toContain("--in-place");
+    expect(prLoopJobs("github", "prod")[1]!.command).toContain("--resume .chant/pr-resume/pr-apply.json");
     const key = "chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}";
     expect(steps[restore].with).toEqual({ path: ".chant/pr-resume/pr-apply.json", key, "restore-keys": "chant-apply-prod-${{ github.sha }}-" });
     // Saved even when the apply failed, which is when a re-run needs it.
@@ -92,7 +113,7 @@ describe("the GitHub pull-request workflow", () => {
     expect(steps[save].with).toEqual({ path: ".chant/pr-resume/pr-apply.json", key });
     // The plan job runs the pull request's code: it neither reads nor writes the record.
     expect(doc.jobs.plan.steps.some((s) => s.uses?.startsWith("actions/cache"))).toBe(false);
-    expect(doc.jobs.plan.steps.find((s) => s.run?.includes("pr-plan"))!.run).not.toContain("--resume");
+    expect(doc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!.run).not.toContain("--resume");
     // The report artifact does not carry the record, which holds the members' outputs.
     const keep = steps.find((s) => s.uses?.startsWith("actions/upload-artifact"))!;
     expect(keep.with?.path).toBe(".chant/pr");
@@ -109,18 +130,20 @@ describe("the GitHub pull-request workflow", () => {
     const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { gate: "infra-apply", branch: "trunk", requireReview: false } }).yaml;
     expect(yaml).toContain("--gate infra-apply");
     expect(yaml).toContain("- trunk");
-    expect(yaml).not.toContain("--require-review");
+    expect(yaml).toContain("--no-require-review");
+    expect(yaml).toContain('--branch "trunk"');
   });
 
-  test("refuses a wave or promote job beside it", () => {
-    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g" } })).toThrow(/pull-request pipeline has no wave or promote jobs/);
-    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, promoteTo: "prod" })).toThrow(/pull-request pipeline has no wave or promote jobs/);
+  test("refuses a promote job beside it, and a canary or a fixed base beside --wave-gate (#4003)", () => {
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, promoteTo: "prod" })).toThrow(/pull-request pipeline has no promote job/);
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g", canary: ["net"] } })).toThrow(/takes no --canary/);
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g", base: "HEAD~1" } })).toThrow(/takes no --base/);
   });
 
   test("events and reportUrl stream the run's events into the report artifact and copy the reports out (#4007)", () => {
     const loud = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { events: true, reportUrl: "s3://chant-reports/acme" } }).yaml) as { jobs: Record<string, Job> };
     for (const job of ["plan", "apply"]) {
-      const run = loud.jobs[job].steps.find((s) => s.run?.startsWith("chant components"))!;
+      const run = loud.jobs[job].steps.find((s) => s.run?.includes("chant ci run"))!;
       expect(run.run).toContain('--events-json --report-url "s3://chant-reports/acme"');
       expect(run.env?.CHANT_RUN_EVENTS_DIR).toBe(".chant/pr/run-events");
     }
@@ -142,13 +165,14 @@ describe("the GitHub pull-request workflow", () => {
     // No path filter: a change outside the member can reach it.
     expect(mdoc.on).toEqual({ pull_request: { branches: ["main"] }, push: { branches: ["main"] } });
     expect(mdoc.defaults).toEqual({ run: { "working-directory": "infra/network" } });
-    const plan = mdoc.jobs.plan.steps.find((s) => s.run?.includes("pr-plan"))!;
-    expect(plan.run).toBe('chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github --member network');
-    const apply = mdoc.jobs.apply.steps.find((s) => s.run?.includes("pr-apply"))!;
-    expect(apply.run).toContain("--member 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(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 });
     // The record path is relative to the member for --resume and to the repository for the cache.
-    expect(apply.run).toContain("--resume .chant/pr-resume/pr-apply.json");
+    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)) {
@@ -172,7 +196,7 @@ describe("the GitHub pull-request workflow", () => {
     const mdoc = parseYAML(yaml) as { name: string; defaults?: unknown; jobs: Record<string, Job> };
     expect(mdoc.name).toBe("chant-pr.root.prod");
     expect(mdoc.defaults).toBeUndefined();
-    expect(yaml).toContain("--member root");
+    expect(yaml).toContain("chant ci run plan --in-place");
     expect(yaml).toContain("path: .chant/pr");
   });