@intentius/chant-lexicon-github 0.124.40 → 0.124.42

package/src/components/generate-pipeline.ts

@@ -59,8 +59,11 @@
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
 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 { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
+import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
 import {
+  APPLY_COMMENT,
   GREEN_TAG_PATTERN,
   GREEN_TICK_WORKFLOW,
   PR_APPLY_RECORD,
@@ -70,9 +73,15 @@ import {
   prApplyRecordKey,
   prApplyWaveJobName,
   prLoopJobs,
+  prLoopPostJob,
   prLoopSetup,
+  PR_PLAN_NOTE_JOB,
   prLoopWaveJobs,
   prLoopWithWaves,
+  prEnvJobs,
+  PR_ENV_REPORT_DIR,
+  PR_ENV_SWEEP_CRON,
+  PR_ENV_POST_JOB,
 } from "@intentius/chant/components/pr-pipeline";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import type {
@@ -81,7 +90,8 @@ import type {
   ComponentPipelineResult as GenerateGithubResult,
   PipelineMember,
 } from "@intentius/chant/lexicon";
-import { checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
+import { afterEarlierWave, checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
+import { actionRef } from "../action-pins";
 
 export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
 
@@ -122,6 +132,9 @@ export interface GithubPipelineDoc {
   jobs: GeneratedJob[];
 }
 
+/** The plan job's last step, whose outputs carry its report to the plan-note job (#4295). */
+const PLAN_STEP_ID = "plan";
+
 /** The output a gated apply wave hands the green commit it applies through, and the step that sets it (#4221). */
 const WAVE_GREEN_OUTPUT = "green-sha";
 const WAVE_STEP_ID = "apply";
@@ -158,6 +171,8 @@ function gatedWaveGithubDoc(
     steps.push(...runSteps(prLoopSetup(image)), ...runSteps(beforeScript), { run: job.command.join(" ") }, ...runSteps(extraScript));
     steps.push(keepRecordStep(`Upload the record for wave ${job.wave}`, waveRecordArtifact(job.wave), GATED_WAVE_RECORD));
     jobsDoc[job.jobName] = {
+      // #4291: a wave runs after one that failed, and blocks only what depends on the failure.
+      ...(job.needs.length > 0 ? { if: afterEarlierWave(job.needs[0]!) } : {}),
       "runs-on": GITHUB_RUNNER,
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       container: image,
@@ -203,6 +218,35 @@ function gatedWaveGithubDoc(
  * 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>`.
+ *
+ * The plan job holds no forge token while the pull request's code runs
+ * (#4295, `@intentius/chant/ci-handover`). It checks the change out with a
+ * script that gives the job's token to its fetches alone, starts every later
+ * step again without the token variables, and ends with the plan step, which
+ * hands its report on as the job's outputs. The `plan-note` job then checks
+ * out the target branch's commit, takes the report back, keeps it as the
+ * `chant-pr-plan` artifact, and posts the note and `chant/plan` with
+ * `chant components pr-post`. Only the note job may write to the pull
+ * request and its statuses.
+ *
+ * With `identity` (#4296, `@intentius/chant/ci-identity`) the plan, record
+ * and apply jobs get `id-token: write`, and each starts with a step that
+ * trades the job's OIDC token for its cloud identity before anything is
+ * checked out: the plan and record jobs for the plan identity, the apply
+ * jobs for the apply identity. The trade leaves the credentials in
+ * `GITHUB_ENV`. Every later step of the plan job starts without the
+ * variables a token is requested with, so the pull request's code holds no
+ * OIDC token and cannot request one, and the plan job names no apply
+ * identity.
+ *
+ * With `applyBeforeMerge` (#4301, ws-106) the apply job runs on a
+ * `/chant apply` comment on a pull request (`issue_comment`), from the
+ * default branch's workflow file, so a pull request cannot change the job
+ * that applies it. It checks out the pull request's head after the setup
+ * and `beforeScript` ran at the default branch's commit, and runs `pr-apply
+ * --before-merge`, which asks the forge the requires checks before any of
+ * the head's code loads. On GitHub the commenter must be an owner, member
+ * or collaborator. A push still records.
  */
 function prLoopGithubDoc(
   components: DriverComponent[],
@@ -235,8 +279,18 @@ function prLoopGithubDoc(
     uses: "actions/cache/save@v4",
     with: { path: recordPath, key: recordKey(wave) },
   });
+  // #4296: the step that trades the job's OIDC token for its cloud identity, before the checkout.
+  const identity = loop.identity;
+  const tradeStep = (spec: CloudTradeSpec, which: "plan" | "apply"): Record<string, unknown> => ({
+    name: `Trade the job's OIDC token for the ${which} identity`,
+    ...(rooted ? {} : { "working-directory": "." }),
+    env: { [TRADE_SPEC_ENV]: JSON.stringify(spec) },
+    run: tradeLine("$GITHUB_ENV", "github-env"),
+  });
+  const withIdToken = (permissions: Record<string, string>): Record<string, string> => (identity ? { ...permissions, "id-token": "write" } : permissions);
   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>> => [
+    ...(identity ? [tradeStep(job.jobName === "record" ? identity.plan : identity.apply, job.jobName === "record" ? "plan" : "apply")] : []),
     checkoutStep(true),
     ...runSteps(prLoopSetup(image)),
     ...runSteps(beforeScript),
@@ -266,13 +320,22 @@ function prLoopGithubDoc(
   const forgejo = loop.forge === "forgejo";
   const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
   const onPush = loop.applyOnMerge && forgejo ? "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')" : "github.event_name == 'push'";
+  // #4301: a `/chant apply` comment on a pull request starts the apply before merge. GitHub also asks for a commenter who can write.
+  const onComment = [
+    "github.event_name == 'issue_comment'",
+    // Forgejo's payload says so with is_pull (terragucci comment-apply.ts:129 at e6cb431).
+    forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+    `startsWith(github.event.comment.body, '${APPLY_COMMENT}')`,
+    ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+  ].join(" && ");
   const applyJob = (job: typeof plan, needs: string[], name: string) => ({
-    if: job.jobName === "record" ? onPush : onGreen,
+    // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
+    if: job.jobName === "record" ? onPush : needs.length > 0 && job.wave ? afterEarlierWave(needs[0]!, onGreen) : onGreen,
     "runs-on": GITHUB_RUNNER,
     ...(needs.length > 0 ? { needs } : {}),
     container: image,
     concurrency: concurrency(prApplyGroup(env, member?.name)),
-    permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
+    permissions: withIdToken({ contents: "write", "pull-requests": "write", statuses: "write" }),
     ...(job.wave ? { outputs: { [WAVE_GREEN_OUTPUT]: `\${{ steps.${WAVE_STEP_ID}.outputs.${WAVE_GREEN_OUTPUT} }}` } } : {}),
     steps: steps(job, name),
   });
@@ -285,44 +348,211 @@ function prLoopGithubDoc(
       ])
     : loop.applyOnMerge
       ? [["apply", applyJob(apply, [], "Apply the newest green commit under the merged changes' approvals")]]
-      : [];
+      : loop.applyBeforeMerge
+        ? [["apply", { ...applyJob(apply, [], "Apply the pull request's head under its gate, once it is approved, mergeable, undiverged and green"), if: onComment }]]
+        : [];
   const applyJobs: Array<[string, Record<string, unknown>]> = [recordJob, ...greenJobs];
+  // #4295: the plan job runs the pull request's code and holds no forge token while it does.
+  const forgeName = loop.forge ?? "github";
+  // #4296: once the plan job has traded its OIDC token, its later steps start without the variables a token is requested with.
+  const drop = dropForgeTokens("sh", identity ? OIDC_REQUEST_VARS : []);
+  const headStep = (line: string, name?: string): Record<string, unknown> => ({ ...(name ? { name } : {}), run: `${drop}\n${line}` });
+  const planSteps: Array<Record<string, unknown>> = [
+    // #4296: the trade runs first, before the change is checked out, with the plan identity alone.
+    ...(identity ? [tradeStep(identity.plan, "plan")] : []),
+    // A script, not actions/checkout, whose post step runs at the job's end with the token as its input.
+    {
+      name: "Check out the change",
+      ...(rooted ? {} : { "working-directory": "." }),
+      env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
+      run: checkoutScript(true, true),
+    },
+    ...[...prLoopSetup(image), ...beforeScript].map((line) => headStep(line)),
+    ...(plan.build ? [headStep(plan.build[0]!, "Build the templates"), headStep(plan.build[1]!, "Lint the project")] : []),
+    // The job's last step: a step after it would start beside whatever the change's code left running.
+    {
+      name: "Plan the members this pull request reaches",
+      id: PLAN_STEP_ID,
+      env: plan.run.env,
+      run: [drop, ...handoverTrap(PR_LOOP_REPORT_DIR, forgeName), ...(plan.checkout ?? []), ...(plan.setup ?? []), plan.run.command, ...extraScript].join("\n"),
+    },
+  ];
+  const post = prLoopPostJob(forgeName, env, member?.name);
+  const noteSteps: Array<Record<string, unknown>> = [
+    // The target branch's commit: the chant this job runs is the target branch's, and none of the change's code is here.
+    { name: "Check out the target branch's commit", uses: actionRef("actions/checkout"), with: { ref: "${{ github.event.pull_request.base.sha }}" } },
+    ...runSteps(beforeScript),
+    { name: "Take the plan report from the plan job", run: takeOverScript("plan", PR_LOOP_REPORT_DIR, forgeName) },
+    { name: "Keep the plan report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: reportName(plan), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } },
+    { name: "Post the plan note and chant/plan", if: "always()", env: post.env, run: post.command },
+  ];
+  // #4298: with a pull request environment the pull_request trigger fires on close too, and the plan skips that event.
+  const prEnv = loop.prEnvironment ? prEnvGithubJobs(loop.forge ?? "github", image, beforeScript, extraScript, loop, member) : undefined;
   const jobsDoc: Record<string, unknown> = {
     plan: {
-      if: "github.event_name == 'pull_request'",
+      if: prEnv ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
       "runs-on": GITHUB_RUNNER,
       container: image,
-      permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
-      steps: steps(plan, "Plan the members this pull request reaches"),
+      permissions: withIdToken({ contents: "read" }),
+      outputs: handoverOutputs(PLAN_STEP_ID, forgeName),
+      steps: planSteps,
+    },
+    [PR_PLAN_NOTE_JOB]: {
+      needs: ["plan"],
+      if: "always() && github.event_name == 'pull_request' && (needs.plan.result == 'success' || needs.plan.result == 'failure')",
+      "runs-on": GITHUB_RUNNER,
+      container: image,
+      // #4289: `actions: read` lets pr-post ask when each scheduled watch or reconcile Op last ran.
+      permissions: { actions: "read", contents: "read", "pull-requests": "write", statuses: "write" },
+      steps: noteSteps,
     },
     ...Object.fromEntries(applyJobs),
+    ...(prEnv ? prEnv.jobs : {}),
   };
   const applyNames = applyJobs.map(([name]) => name);
+  const on: Record<string, unknown> = !loop.applyOnMerge
+    ? { pull_request: { branches: [branch] }, push: { branches: [branch] } }
+    : forgejo
+      ? { pull_request: { branches: [branch] }, push: { branches: [branch], tags: [GREEN_TAG_PATTERN] } }
+      : { pull_request: { branches: [branch] }, push: { branches: [branch] }, workflow_run: { workflows: [GREEN_TICK_WORKFLOW], types: ["completed"] }, workflow_dispatch: {} };
+  if (prEnv) {
+    on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
+    on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
+  }
+  // #4301: a /chant apply comment starts the apply before merge.
+  if (loop.applyBeforeMerge) on.issue_comment = { types: ["created"] };
   return {
     name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
     environment: env,
-    on: !loop.applyOnMerge
-      ? { pull_request: { branches: [branch] }, push: { branches: [branch] } }
-      : forgejo
-        ? { pull_request: { branches: [branch] }, push: { branches: [branch], tags: [GREEN_TAG_PATTERN] } }
-        : { pull_request: { branches: [branch] }, push: { branches: [branch] }, workflow_run: { workflows: [GREEN_TICK_WORKFLOW], types: ["completed"] }, workflow_dispatch: {} },
+    on,
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", ...applyNames],
+    stages: ["plan", PR_PLAN_NOTE_JOB, ...applyNames, ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
     jobs: [
       { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
+      { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
       ...applyNames.map((name, i) => ({
         jobName: name,
-        component: name === "record" ? "merge record" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
+        component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
         stage: name,
         // The record runs on a push and the apply on a green commit, so only the waves need each other.
         needs: i > 1 ? [applyNames[i - 1]] : [],
       })),
+      ...(prEnv ? prEnv.listed : []),
     ],
   };
 }
 
+/**
+ * The jobs of a pull request's environment (#4298). `env-up` runs on an
+ * opened, updated or reopened pull request and runs the change's code, so it
+ * follows the plan job's handover (#4295): a checkout script that alone sees
+ * the job's token, every later step started without the token variables,
+ * and the `pr-env up` step last, handing its report and record on as the
+ * job's outputs. `env-post` checks out the target branch's commit, takes
+ * them back, keeps the record on chant/lifecycle and posts the note.
+ * `env-down` runs when the pull request closes and `env-sweep` on the
+ * schedule, both from the base branch's code: a teardown reads the markers
+ * off the live resources and builds nothing of the change. `env-up` and
+ * `env-down` run one at a time per pull request, and a close waits for an
+ * apply still running rather than cancelling it.
+ */
+function prEnvGithubJobs(
+  forge: "github" | "forgejo",
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  loop: NonNullable<GenerateGithubOptions["prLoop"]>,
+  member: GenerateGithubOptions["member"],
+): { jobs: Record<string, unknown>; listed: GeneratedJob[] } {
+  const [up, post, down, sweep] = prEnvJobs(forge, loop, member?.name);
+  const rooted = !member || member.dir === "." || member.dir === "";
+  const reportPath = member ? memberRepoPath(member, PR_ENV_REPORT_DIR) : PR_ENV_REPORT_DIR;
+  const prNumber = "${{ github.event.pull_request.number }}";
+  const group = `chant-pr-env-${member ? `${member.name}-` : ""}${prNumber}`;
+  const writes = { contents: "write", "pull-requests": "write", statuses: "write" };
+  const keep = (name: string) => ({ name: `Keep the ${name} report`, if: "always()", uses: UPLOAD_ARTIFACT, with: { name: `chant-pr-${name}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } });
+  const opened = "github.event_name == 'pull_request' && github.event.action != 'closed'";
+
+  // #4295: env-up runs the change's code and holds no forge token while it does.
+  const drop = dropForgeTokens("sh");
+  const headStep = (line: string, name?: string, env?: Record<string, string>): Record<string, unknown> => ({ ...(name ? { name } : {}), ...(env ? { env } : {}), run: `${drop}\n${line}` });
+  const upJob = {
+    if: opened,
+    "runs-on": GITHUB_RUNNER,
+    container: image,
+    concurrency: concurrency(group),
+    permissions: { contents: "read" },
+    outputs: handoverOutputs(PR_ENV_UP_STEP_ID, forge),
+    steps: [
+      {
+        name: "Check out the change",
+        ...(rooted ? {} : { "working-directory": "." }),
+        env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
+        run: checkoutScript(true, true),
+      },
+      ...[...prLoopSetup(image), ...beforeScript].map((line) => headStep(line)),
+      ...(up.build ? [headStep(up.build[0]!, "Build the templates", { CHANT_ENV: up.env.CHANT_ENV! }), headStep(up.build[1]!, "Lint the project")] : []),
+      // The job's last step: a step after it would start beside whatever the change's code left running.
+      {
+        name: "Apply this pull request's environment once its plan is approved",
+        id: PR_ENV_UP_STEP_ID,
+        env: up.env,
+        run: [drop, ...handoverTrap(PR_ENV_REPORT_DIR, forge), up.command, ...extraScript].join("\n"),
+      },
+    ],
+  };
+  const postJob = {
+    needs: ["env-up"],
+    if: `always() && ${opened} && (needs.env-up.result == 'success' || needs.env-up.result == 'failure')`,
+    "runs-on": GITHUB_RUNNER,
+    container: image,
+    concurrency: concurrency(`chant-pr-env-post-${member ? `${member.name}-` : ""}${prNumber}`),
+    permissions: writes,
+    steps: [
+      // The target branch's commit: the chant this job runs is the target branch's, and none of the change's code is here.
+      { name: "Check out the target branch's commit", uses: actionRef("actions/checkout"), with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
+      ...runSteps(beforeScript),
+      { name: "Take the environment's report from the env-up job", run: takeOverScript("env-up", PR_ENV_REPORT_DIR, forge) },
+      keep("env-up"),
+      { name: "Keep the environment's record and post its note", if: "always()", env: post.env, run: post.command },
+    ],
+  };
+  const baseJob = (j: typeof up, condition: string, ref: string, name: string, groupName: string) => ({
+    if: condition,
+    "runs-on": GITHUB_RUNNER,
+    container: image,
+    concurrency: concurrency(groupName),
+    permissions: writes,
+    steps: [
+      { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0, ...(ref ? { ref } : {}) } },
+      ...runSteps(prLoopSetup(image)),
+      ...runSteps(beforeScript),
+      { name, env: j.env, run: j.command },
+      ...runSteps(extraScript),
+      keep(j.jobName),
+    ],
+  });
+  return {
+    jobs: {
+      "env-up": upJob,
+      [PR_ENV_POST_JOB]: postJob,
+      "env-down": baseJob(down, "github.event_name == 'pull_request' && github.event.action == 'closed'", "${{ github.event.pull_request.base.ref }}", "Tear down what this pull request's environment owns", group),
+      "env-sweep": baseJob(sweep, "github.event_name == 'schedule'", "", "Tear down the environments whose TTL passed or whose pull request closed", `chant-pr-env-sweep${member ? `-${member.name}` : ""}`),
+    },
+    listed: [
+      { jobName: "env-up", component: "pull request environment", stage: "env-up", needs: [] },
+      { jobName: PR_ENV_POST_JOB, component: "pull request environment note", stage: PR_ENV_POST_JOB, needs: ["env-up"] },
+      { jobName: "env-down", component: "pull request environment teardown", stage: "env-down", needs: [] },
+      { jobName: "env-sweep", component: "pull request environment sweep", stage: "env-sweep", needs: [] },
+    ],
+  };
+}
+
+/** The id of the `pr-env up` step, whose outputs carry the report (#4295). */
+const PR_ENV_UP_STEP_ID = "env-up";
+
 /** The file a producer dumps its resolved outputs to, and a dependent seeds from — one per component, matching gitlab's naming so both generators produce interchangeable artifacts. */
 function outputsFile(name: string): string {
   return `${name}.outputs.json`;

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

@@ -0,0 +1,206 @@
+/**
+ * A pull request's environment in the generated GitHub workflow (#4298):
+ * `env-up` on an opened, updated or reopened pull request, `env-post` after
+ * it, `env-down` when it closes, `env-sweep` on the schedule, and a plan job
+ * that skips the close.
+ *
+ * `env-up` runs the pull request's code, so it follows the handover (#4295):
+ * only its checkout sees the job's token, every later step starts without
+ * the token variables, and the `pr-env up` step is last and hands its report
+ * and record on. The behaviour test runs the generated steps with `sh`, as a
+ * forge runs them, with every token variable set.
+ */
+
+import { execFileSync, 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 { PR_ENV_SWEEP_CRON } from "@intentius/chant/components/pr-pipeline";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "kubectl-apply", manifest: "app.yaml" } as never] }] }];
+
+interface Step {
+  name?: string;
+  id?: string;
+  if?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+}
+interface Job {
+  if: string;
+  needs?: string[];
+  permissions: Record<string, string>;
+  outputs?: Record<string, string>;
+  concurrency: { group: string; "cancel-in-progress": boolean };
+  steps: Step[];
+}
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const SECRET = "ghs_generated_env_secret_4298";
+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 UP_LINE = /^chant components pr-env up .*$/m;
+
+function hasActionlint(): boolean {
+  try {
+    execFileSync("actionlint", ["-version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function workflow(): { yaml: string; jobs: string[]; doc: { on: Record<string, unknown>; jobs: Record<string, Job> } } {
+  const result = generateGithubPipeline(ESTATE, { env: "staging", image: "example/ci:1", beforeScript: ["npm ci"], extraScript: ["echo after"], prLoop: { prEnvironment: true, build: true } });
+  return { yaml: result.yaml, jobs: result.jobs.map((j) => j.jobName), doc: parseYAML(result.yaml) as { on: Record<string, unknown>; jobs: Record<string, Job> } };
+}
+
+describe("the GitHub pull-request workflow with a pull request environment", () => {
+  const { yaml, jobs, doc } = workflow();
+
+  test("the pull_request trigger fires on close too, and a schedule starts the sweep", () => {
+    expect(doc.on.pull_request).toEqual({ branches: ["main"], types: ["opened", "synchronize", "reopened", "closed"] });
+    expect(doc.on.schedule).toEqual([{ cron: PR_ENV_SWEEP_CRON }]);
+    expect(doc.jobs.plan!.if).toBe("github.event_name == 'pull_request' && github.event.action != 'closed'");
+    expect(jobs).toEqual(expect.arrayContaining(["env-up", "env-post", "env-down", "env-sweep"]));
+  });
+
+  test("env-up plans pr-<n> with no forge and no push; env-down tears it down from the base branch", () => {
+    const up = doc.jobs["env-up"]!;
+    const down = doc.jobs["env-down"]!;
+    expect(up.if).toBe("github.event_name == 'pull_request' && github.event.action != 'closed'");
+    expect(down.if).toBe("github.event_name == 'pull_request' && github.event.action == 'closed'");
+    const last = up.steps.at(-1)!;
+    expect(last.run).toMatch(UP_LINE);
+    expect(last.run!.match(UP_LINE)![0]).toBe('chant components pr-env up --base "$BASE_SHA" --pr "$PR_NUMBER" --output .chant/pr-env --no-push');
+    expect(last.env?.CHANT_ENV).toBe("pr-${{ github.event.pull_request.number }}");
+    const downRun = down.steps.find((s) => s.run?.startsWith("chant components pr-env"))!;
+    expect(downRun.run).toBe('chant components pr-env down --pr "$PR_NUMBER" --reason closed --forge github --output .chant/pr-env');
+    expect(down.steps[0]!.with?.ref).toBe("${{ github.event.pull_request.base.ref }}");
+    expect(up.concurrency).toEqual({ group: "chant-pr-env-${{ github.event.pull_request.number }}", "cancel-in-progress": false });
+    expect(down.concurrency).toEqual(up.concurrency);
+    expect(doc.jobs["env-sweep"]!.if).toBe("github.event_name == 'schedule'");
+  });
+
+  test("without the option nothing changes", () => {
+    const plain = parseYAML(generateGithubPipeline(ESTATE, { env: "staging", prLoop: {} }).yaml) as { on: Record<string, unknown>; jobs: Record<string, Job> };
+    expect(plain.on.pull_request).toEqual({ branches: ["main"] });
+    expect(plain.jobs["env-up"]).toBeUndefined();
+  });
+
+  test.skipIf(!hasActionlint())("passes actionlint", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-actionlint-"));
+    dirs.push(dir);
+    mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+    writeFileSync(join(dir, ".github", "workflows", "chant-pr.yml"), yaml);
+    expect(() => execFileSync("actionlint", [".github/workflows/chant-pr.yml"], { cwd: dir, encoding: "utf8" })).not.toThrow();
+  });
+});
+
+describe("env-up holds no forge token while the pull request's code runs (#4295)", () => {
+  const { doc } = workflow();
+  const up = doc.jobs["env-up"]!;
+  const post = doc.jobs["env-post"]!;
+
+  test("only the checkout step is given the job's token, and only for its fetches", () => {
+    const [checkout, ...rest] = up.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);
+    }
+    expect(up.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 up.steps.slice(1)) {
+      expect(step.uses).toBeUndefined();
+      expect(step.run!.split("\n")[0]).toBe(dropForgeTokens("sh"));
+    }
+  });
+
+  test("the pr-env up step is the job's last and hands its report on as the job's outputs", () => {
+    const last = up.steps.at(-1)!;
+    expect(last.id).toBe("env-up");
+    expect(last.run!.trimEnd().split("\n").at(-1)).toBe("echo after");
+    expect(up.outputs).toEqual({ report_0: "${{ steps.env-up.outputs.report_0 }}" });
+  });
+
+  test("env-post checks out the target branch's commit, and only it can write the record, the note and the status", () => {
+    expect(post.needs).toEqual(["env-up"]);
+    expect(post.if).toContain("needs.env-up.result == 'failure'");
+    expect(post.steps[0]).toMatchObject({ uses: expect.stringMatching(/^actions\/checkout@/), with: { ref: "${{ github.event.pull_request.base.sha }}" } });
+    expect(post.permissions).toEqual({ contents: "write", "pull-requests": "write", statuses: "write" });
+    const last = post.steps.at(-1)!;
+    expect(last.env).toMatchObject({ GITHUB_TOKEN: "${{ github.token }}", HEAD_SHA: "${{ github.sha }}", UP_RESULT: "${{ needs.env-up.result }}" });
+    expect(last.run).toBe('chant components pr-env post --pr "$PR_NUMBER" --head "$HEAD_SHA" --forge github --output .chant/pr-env --result "$UP_RESULT"');
+    // The post job runs no build, no lint and no pr-env up: none of the change's code.
+    expect(JSON.stringify(post)).not.toMatch(/chant (build|lint)|pr-env up/);
+  });
+});
+
+/** 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("env-up's steps, run, see no forge token and hand the report and record 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-env-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["env-up"]!.steps.slice(1);
+    steps.forEach((step, i) => {
+      const probe = `env > "${seen}/${i}.env"; sh -c 'env' >> "${seen}/${i}.env"`;
+      const report = "mkdir -p .chant/pr-env && echo '{\"stage\":\"up\"}' > .chant/pr-env/pr-env-up.json && echo '{\"kind\":\"up\"}' > .chant/pr-env/pr-env-record.json";
+      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, ...(UP_LINE.test(step.run!) ? [report] : [])].join("\n");
+      expect(runStep({ run: body }, work, { GITHUB_OUTPUT: output, BASE_SHA: "b".repeat(40), PR_NUMBER: "7" }), step.name ?? lines[1]).toBe(0);
+    });
+    for (let i = 0; i < steps.length; i++) expect(readFileSync(join(seen, `${i}.env`), "utf-8")).not.toContain(SECRET);
+    expect(readFileSync(output, "utf-8")).toMatch(/^report_0=\S+$/m);
+  });
+
+  test("env-post's take-over step writes the report and the record back from that output", () => {
+    const top = mkdtempSync(join(tmpdir(), "chant-generated-env-post-"));
+    dirs.push(top);
+    const work = join(top, "work");
+    mkdirSync(join(work, ".chant", "pr-env"), { recursive: true });
+    writeFileSync(join(work, ".chant", "pr-env", "pr-env-up.json"), '{"stage":"up"}\n');
+    writeFileSync(join(work, ".chant", "pr-env", "pr-env-record.json"), '{"kind":"up"}\n');
+    const output = join(top, "github-output");
+    const upStep = doc.jobs["env-up"]!.steps.at(-1)!;
+    const handOn = upStep.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 postWork = join(top, "post");
+    mkdirSync(postWork);
+    const take = doc.jobs["env-post"]!.steps.find((s) => s.name === "Take the environment's report from the env-up job")!;
+    const filled = take.run!.replace("${{ toJSON(needs.env-up.outputs.report_0) }}", JSON.stringify(value));
+    expect(runStep({ run: filled }, postWork, {})).toBe(0);
+    expect(existsSync(join(postWork, ".chant", "pr-env", "pr-env-record.json"))).toBe(true);
+    expect(readFileSync(join(postWork, ".chant", "pr-env", "pr-env-up.json"), "utf-8")).toBe('{"stage":"up"}\n');
+  });
+});

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

@@ -0,0 +1,67 @@
+/**
+ * The pull-request workflow with an apply before merge (#4301, ws-106): a
+ * `/chant apply` comment starts the apply job from the default branch's
+ * workflow, which checks out the pull request's head and runs `pr-apply
+ * --before-merge` through `chant ci run`. A push still records.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { prLoopJobs, pullRequestCheckout } from "@intentius/chant/components/pr-pipeline";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+interface Step { name?: string; run?: string; env?: Record<string, string> }
+interface Job { if: string; permissions: Record<string, string>; steps: Step[] }
+
+describe("the GitHub workflow with --apply-before-merge", () => {
+  const doc = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyBeforeMerge: true } }).yaml) as { on: Record<string, unknown>; jobs: Record<string, Job> };
+
+  test("listens to new comments beside pull requests and pushes, and keeps the record job on a push", () => {
+    expect(doc.on).toEqual({ pull_request: { branches: ["main"] }, push: { branches: ["main"] }, issue_comment: { types: ["created"] } });
+    expect(Object.keys(doc.jobs)).toEqual(["plan", "plan-note", "record", "apply"]);
+    expect(doc.jobs.record!.if).toBe("github.event_name == 'push'");
+  });
+
+  test("the apply runs on a /chant apply comment on a pull request from someone who can write", () => {
+    const cond = doc.jobs.apply!.if;
+    expect(cond).toContain("github.event_name == 'issue_comment'");
+    expect(cond).toContain("github.event.issue.pull_request");
+    expect(cond).toContain("startsWith(github.event.comment.body, '/chant apply')");
+    expect(cond).toContain("github.event.comment.author_association");
+  });
+
+  test("it checks out the pull request's head in its run step and applies before merge with the target branch's commit as the base", () => {
+    const step = doc.jobs.apply!.steps.find((s) => s.run?.includes("chant ci run apply"))!;
+    const lines = step.run!.trimEnd().split("\n");
+    expect(lines[0]).toBe(pullRequestCheckout("github"));
+    expect(lines.at(-1)).toBe('chant ci run apply --in-place --base "$BASE_SHA" --pr "$PR_NUMBER" --apply-before-merge --env prod --gate pr-apply --forge github');
+    expect(step.env).toMatchObject({ BASE_SHA: "${{ github.sha }}", PR_NUMBER: "${{ github.event.issue.number }}" });
+  });
+
+  test("the command chant ci run rebuilds asks pr-apply for the apply before merge", () => {
+    const apply = prLoopJobs("github", "prod", { applyBeforeMerge: true }).find((j) => j.jobName === "apply")!;
+    expect(apply.command).toBe('chant components pr-apply --before-merge --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github --resume .chant/pr-resume/pr-apply.json');
+  });
+
+  test("it takes no apply on merge, no wave gate and no build", () => {
+    expect(() => prLoopJobs("github", "prod", { applyBeforeMerge: true, applyOnMerge: true })).toThrow(/--apply-on-merge/);
+    expect(() => prLoopJobs("github", "prod", { applyBeforeMerge: true, waveGate: "w" })).toThrow(/--wave-gate/);
+    expect(() => prLoopJobs("github", "prod", { applyBeforeMerge: true, build: true })).toThrow(/--pr-build/);
+  });
+
+  test("the pull request checkout refuses a number that is not one", () => {
+    expect(pullRequestCheckout("github")).toMatch(/^echo "\$PR_NUMBER" \| grep -Eq '\^\[0-9\]\+\$' && git fetch --quiet origin "\+refs\/pull\/\$PR_NUMBER\/head:/);
+    expect(pullRequestCheckout("gitlab")).toContain("refs/merge-requests/$PR_NUMBER/head");
+  });
+
+  test("on Forgejo the comment may also say so with is_pull, and there is no author association", () => {
+    const forgejo = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyBeforeMerge: true, forge: "forgejo" } }).yaml) as { jobs: Record<string, Job> };
+    expect(forgejo.jobs.apply!.if).toContain("(github.event.issue.pull_request || github.event.is_pull)");
+    expect(forgejo.jobs.apply!.if).not.toContain("author_association");
+  });
+});