@intentius/chant-lexicon-gitlab 0.124.54 → 0.124.56

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

@@ -24,8 +24,9 @@
  * arrived, with `CHANT_FORGE_TOKEN` (a project access token with the `api`
  * scope and the Developer role; the job token cannot retry jobs).
  *
- * A `pr-review` wave (#3684) adds `<name>-record-plans`, run in merge request
- * pipelines only, which records the digests the merge request's head plans.
+ * A `pr-review` wave (#3684), or a `pull-request` wave (#4630), adds
+ * `<name>-record-plans`, run in merge request pipelines only, which records
+ * the digests the merge request's head plans.
  *
  * `runner` (on the spec, a wave or a job group, #3914) is the job's `tags:`; a
  * GitHub runner group is a spec error here. A wave's `jobs` renders its
@@ -37,6 +38,26 @@
  * entry per cloud, and its script starts by trading them for those
  * identities and unsetting the token variables, before any line of the
  * checkout runs.
+ *
+ * With `control` on the spec (#4617), a `control-dispatch` job in a
+ * `control` stage needs the last wave's jobs, whose artifacts hold every
+ * job's outcome file. It adds them up with `chant run wave --waves-outcome`
+ * (through the product's bin) into `CHANT_CONTROL_OUTCOME` and sends the
+ * control repo one dispatch carrying it and `$CI_COMMIT_SHA`. A last wave
+ * whose runs failed (exit 1) still lets it run; a wave that waits at its
+ * gate stops it with the waves, and it runs once the retried job carries
+ * on. A CI/CD variable reaches every job, so every other job starts by
+ * unsetting the control repo's token variables and the product's two
+ * secret names; the dispatch step reads the token from the product's
+ * variable alone and hands it to curl on its stdin (#4568).
+ *
+ * Each wave job's script starts with the apply-job guard (#4624,
+ * `@intentius/chant/ci-job-guard`), before the trade: it stops the job
+ * unless `CI_COMMIT_REF_NAME` is one of the spec's branches and protected,
+ * `CI_ENVIRONMENT_NAME` is the job's environment, and `CI_RUNNER_TAGS`
+ * holds each of the job's tags. A refused guard exits chant's `misplaced`
+ * (9), outside the job's allowed failure, so the job fails and the waves
+ * after it stop.
  */
 
 import {
@@ -55,14 +76,34 @@ import {
   nonEmpty,
   pushBranches,
 } from "@intentius/chant/ci-jobs";
-import { opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import {
+  opWaveGroupOf,
+  opWaveJobs,
+  opWaveOutcomeDir,
+  opWavesControlTarget,
+  opWavesLastJobs,
+  OP_WAVES_APPROVAL_STATUS_VAR,
+  opWavesApprovalStatusCommand,
+  opWavesPostsApprovalStatus,
+  opWavesOutcomeCommand,
+  opWavesRecordPlansCommand,
+  opWavesResumeCommand,
+  type OpWavesSpec,
+} from "@intentius/chant/op/op-waves";
+import { CONTROL_OUTCOME_VAR, CONTROL_TOKEN_VARS, controlDispatchJob } from "@intentius/chant/control/dispatch";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
 import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
+import { JOB_GUARD_ENV, jobGuardLine, jobGuardSpec, opWaveJobLabel } from "@intentius/chant/ci-job-guard";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { resolveProductWords } from "@intentius/chant/ci-product-words";
 import { emitGitlabFile } from "./ci-jobs";
 
+/** The one exit an op-wave job allows as a failure (#4322): a run that failed. The guard's refusal (9) is outside it. */
+export const OP_WAVE_ALLOWED_EXIT = CHANT_EXIT.failed;
+
 /** Render an Op waves spec as one GitLab CI file, `<name>.gitlab-ci.yml` unless `opsFileName` names another. */
 export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult {
-  const jobs = opWaveJobs(spec, options.specFile);
+  const jobs = opWaveJobs(spec, options.specFile, { bin: options.bin });
   const image = options.image ?? CI_IMAGE;
   const subject = `Op waves "${spec.name}"`;
   const rules = pushBranches(spec.branches).map((branch) => {
@@ -84,9 +125,15 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
     }
   }
   const specTags = gitlabTags(spec.runner);
+  const product = resolveProductWords(options.words ?? {}).product;
 
-  const byReview = spec.waves.some((w) => w.approval === "pr-review");
+  // #4630: a pr-review or pull-request wave records each head's plans and posts the approval status.
+  const byReview = opWavesPostsApprovalStatus(spec);
   const stages = [...(byReview ? ["plans"] : []), ...spec.waves.map((wave, i) => `wave-${i + 1}-${wave.name}`)];
+  // #4617: the control repo's token variables, which every job but the dispatch drops first.
+  const control = spec.control ? opWavesControlTarget(spec.control) : undefined;
+  const dropControl = control ? [`unset ${[...new Set([...CONTROL_TOKEN_VARS, control.tokenSecret, control.readTokenSecret])].join(" ")}`] : [];
+  if (control) stages.push("control");
   if (spec.resume) stages.push("resume");
   const entries: Array<readonly [string, unknown]> = [["stages", stages]];
   const variables = nonEmpty("variables", options.variables).variables;
@@ -100,7 +147,19 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
         ...(specTags ? { tags: specTags } : {}),
         variables: { ...GITLAB_FULL_HISTORY },
         rules: [{ if: GITLAB_MERGE_REQUEST_SOURCE }],
-        script: [...(options.beforeScript ?? []), ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ")],
+        script: [...dropControl, ...(options.beforeScript ?? []), opWavesRecordPlansCommand(options.specFile, options.bin).join(" ")],
+      },
+    ]);
+    // #4630: a GitLab approval starts no pipeline, so a schedule of the target branch posts every open merge request's status.
+    entries.push([
+      `${spec.name}-approval-status`,
+      {
+        stage: "plans",
+        image,
+        ...(specTags ? { tags: specTags } : {}),
+        variables: { ...GITLAB_FULL_HISTORY },
+        rules: [{ if: `${GITLAB_SCHEDULE_SOURCE} && $${OP_WAVES_APPROVAL_STATUS_VAR} == "1"` }],
+        script: [...dropControl, ...(options.beforeScript ?? []), opWavesApprovalStatusCommand(options.specFile, "gitlab", options.bin).join(" ")],
       },
     ]);
   }
@@ -114,6 +173,16 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
     const cloud = group?.cloud ?? wave.cloud;
     const declared = gitlabIdTokensDoc(group?.idTokens ?? wave.idTokens);
     const idTokens = cloud ? { ...declared, ...gitlabTradeIdTokens(cloud) } : declared;
+    // #4624: the apply-job guard, the script's first line, before the trade.
+    const runner = group?.runner ?? wave.runner ?? spec.runner;
+    const guard = jobGuardSpec({
+      forge: "gitlab",
+      job: opWaveJobLabel(spec.name, job),
+      product,
+      ...(environment ? { environment: environment.name } : {}),
+      branches: pushBranches(spec.branches),
+      ...(runner !== undefined ? { runner } : {}),
+    });
     entries.push([
       job.jobName,
       {
@@ -123,16 +192,52 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
         resource_group: `${spec.name}-${wave.name}`,
         ...(environment ? { environment: environmentDoc(environment) } : {}),
         ...(idTokens ? { id_tokens: idTokens } : {}),
-        variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}), ...(group?.variables ?? {}), ...(cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(cloud) } : {}) },
+        variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}), ...(group?.variables ?? {}), ...(cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(cloud) } : {}), [JOB_GUARD_ENV]: JSON.stringify(guard) },
         rules,
         ...(job.needs.length > 0 ? { needs: job.needs } : {}),
-        script: [...(cloud ? gitlabTradeLines() : []), ...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
-        // #4322: a run that failed, or was blocked, lets the next wave run; any other failure stops it.
-        allow_failure: { exit_codes: [1] },
+        script: [jobGuardLine(), ...(cloud ? gitlabTradeLines() : []), ...dropControl, ...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
+        // #4322: a run that failed, or was blocked, lets the next wave run; any other failure stops it,
+        // a refused guard (9, #4624) included.
+        allow_failure: { exit_codes: [OP_WAVE_ALLOWED_EXIT] },
         artifacts: { when: "always", paths: [...(job.kind === "decide" ? [job.record!] : []), `${opWaveOutcomeDir(spec)}/`], expire_in: "30 days" },
       },
     ]);
   }
+  if (control) {
+    const dispatch = controlDispatchJob("gitlab", control, "$CI_COMMIT_SHA", {
+      ...(options.words ? { words: options.words } : {}),
+      ...(spec.control!.sentCheck ? { sentCheck: spec.control!.sentCheck } : {}),
+      ...(spec.control!.markSent ? { markSent: spec.control!.markSent } : {}),
+      outcome: true,
+    });
+    entries.push([
+      dispatch.name,
+      {
+        stage: "control",
+        image,
+        ...(specTags ? { tags: specTags } : {}),
+        rules,
+        // The last wave's jobs hand on every job's outcome file through their artifacts.
+        needs: opWavesLastJobs(jobs),
+        // The setup and the outcome run in a subshell without the control token, and only the outcome reaches stdout.
+        script: [
+          [
+            'outcome="$(',
+            ...dropControl,
+            "{ :",
+            ...setupOf[0]!,
+            ...(options.beforeScript ?? []),
+            "} 1>&2",
+            opWavesOutcomeCommand(options.specFile, options.bin).join(" "),
+            ')" || exit 1',
+          ].join("\n"),
+          `export ${CONTROL_OUTCOME_VAR}="$outcome"`,
+          ...Object.entries(dispatch.env).map(([k, v]) => `export ${k}="${v}"`),
+          `bash <<'CONTROL_DISPATCH' || exit $?\n${dispatch.script}\nCONTROL_DISPATCH`,
+        ],
+      },
+    ]);
+  }
   if (spec.resume) {
     entries.push([
       `${spec.name}-resume`,
@@ -141,7 +246,7 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
         image,
         ...(specTags ? { tags: specTags } : {}),
         rules: [{ if: GITLAB_SCHEDULE_SOURCE }],
-        script: [...(options.beforeScript ?? []), opWavesResumeCommand(spec).join(" ")],
+        script: [...dropControl, ...(options.beforeScript ?? []), opWavesResumeCommand(spec, options.bin).join(" ")],
       },
     ]);
   }
@@ -149,10 +254,16 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
     `# chant Op waves "${spec.name}": one stage per wave, each needing the one before.`,
     "# A wave that waits at its gate exits 3 and stops the waves after it; approve the",
     "# digest it prints, then retry the job. A job whose runs failed exits 1, an allowed",
-    "# failure, and the waves after it run what does not depend on those runs.",
+    "# failure, and the waves after it run what does not depend on those runs. A job",
+    "# whose guard finds it running where the spec did not set it to run exits 9 and",
+    "# stops the waves after it.",
     ...(spec.resume
       ? [`# The ${spec.name}-resume job retries it for you in a pipeline schedule; give the schedule the cron "${spec.resume.schedule}".`]
       : []),
+    ...(byReview
+      ? [`# The ${spec.name}-approval-status job posts each open merge request's approval status from a pipeline schedule that sets ${OP_WAVES_APPROVAL_STATUS_VAR}=1.`]
+      : []),
+    ...(control ? [`# After the last wave, the control-dispatch job tells ${control.repo} how the waves ended.`] : []),
   ];
   const name = options.opsFileName ?? `${spec.name}.gitlab-ci.yml`;
   return { files: [{ name, yaml: emitGitlabFile(entries, header) }], jobs };

package/src/components/generate-pipeline.ts

@@ -34,12 +34,14 @@
 
 import {
   assertGitlabBranch,
+  assertRunnerLabels,
   CI_IMAGE,
   ciJobName,
   fillCommand,
   GITLAB_FULL_HISTORY,
   GITLAB_MERGE_REQUEST_SOURCE,
   gitlabPushRule,
+  gitlabTags,
 } from "@intentius/chant/ci-jobs";
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
@@ -61,11 +63,19 @@ import {
   prLoopWaveJobs,
   prLoopWithWaves,
   prEnvJobs,
+  prCommentLockJobs,
+  prCommentPreviewJob,
   PR_ENV_REPORT_DIR,
   PR_ENV_POST_JOB,
+  PR_STALE_JOB,
+  prStaleJob,
+  prLoopJobStage,
+  prLoopRunner,
 } from "@intentius/chant/components/pr-pipeline";
+import { REPO_APPLY_GROUP } from "@intentius/chant/components/repo-lock";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
 import { FORGE_TOKEN_VARS, GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { CONTROL_TOKEN_VARS, controlDispatchJob, controlNoteCheckout } from "@intentius/chant/control/dispatch";
 import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV, type CloudTradeSpec } from "@intentius/chant/ci-identity";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -358,6 +368,9 @@ function gitlabPlanNotesRule(branch: string): string {
   return `$CI_PIPELINE_SOURCE =~ /^(schedule|web|api|trigger)$/ && $${GITLAB_PLAN_NOTES_VAR} == "1" && $CI_COMMIT_BRANCH == ${branch}`;
 }
 
+/** Drops the credentials GitLab's runner writes into origin's URL (#4620), before a merge request's code runs in a pipeline of the target branch. */
+const GITLAB_SCRUB_ORIGIN = `git remote set-url origin "$(git remote get-url origin | sed -E 's#//[^@/]*@#//#')"`;
+
 /** The rule of a pipeline for a pushed `ci/green/` tag (#4168 step 9), which runs the apply under apply on merge. */
 const GITLAB_GREEN_TAG_RULE = '$CI_COMMIT_TAG =~ /^ci\\/green\\//';
 
@@ -397,7 +410,7 @@ function prLoopGitlabPipeline(
   // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY variable is set.
   // #4221: a wave job hands the commit it applies to the next wave as GREEN_SHA, through a dotenv report.
   const handOff = (job: typeof plan): string[] => (job.wave ? [`echo "GREEN_SHA=$GREEN_SHA" > "$CI_PROJECT_DIR/${WAVE_GREEN_DOTENV}"`] : []);
-  const script = (job: typeof plan): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.checkout ?? []), ...handOff(job), ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
+  const script = (job: typeof plan): string[] => [...prLoopSetup(image, loop.engineSetup), ...enter, ...beforeScript, ...(job.checkout ?? []), ...handOff(job), ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
   // #4296: each job trades its OIDC token for its cloud identity before anything else in its script.
   const identity = loop.identity;
   const trading = (spec: CloudTradeSpec | undefined): Record<string, unknown> =>
@@ -406,13 +419,46 @@ function prLoopGitlabPipeline(
   const applySpec = (job: typeof plan): CloudTradeSpec | undefined => (identity ? (job.jobName === "record" ? identity.plan : identity.apply) : undefined);
   // #4298: a pull request environment's jobs, in a stage of their own after the plan.
   const prEnv = loop.prEnvironment ? prEnvGitlabJobs(image, beforeScript, extraScript, enter, loop, member, named, onMergeRequest) : undefined;
-  const stages = ["plan", PR_PLAN_NOTE_JOB, ...applies.map((a) => a.stage), ...(prEnv ? [PR_ENV_STAGE, PR_ENV_POST_STAGE] : [])];
+  // #4568: once the last apply on merge succeeded, one job tells the control repo this member applied.
+  const lastGreen = loop.control && !loop.applyBeforeMerge && greens.length > 0 ? greens[greens.length - 1]!.name : undefined;
+  const control =
+    loop.control && lastGreen
+      ? controlDispatchJob("gitlab", loop.control.target, loop.waveGate ? "$GREEN_SHA" : "$CI_COMMIT_SHA", {
+          ...(loop.words ? { words: loop.words } : {}),
+          ...(loop.control.sentCheck ? { sentCheck: loop.control.sentCheck } : {}),
+          ...(loop.control.markSent ? { markSent: loop.control.markSent } : {}),
+        })
+      : undefined;
+  const controlJob = control ? named(control.name) : undefined;
+  // A CI/CD variable reaches every job, so the plan job drops the control repo's tokens with the forge tokens.
+  const dropControl = loop.control
+    ? [`unset ${[...new Set([...CONTROL_TOKEN_VARS, loop.control.target.tokenSecret, loop.control.target.readTokenSecret])].join(" ")}`]
+    : [];
+  // #4588: `/<product> lock` and `/<product> unlock`: GitLab starts no pipeline on a note, so each runs in a
+  // pipeline of the target branch started with CHANT_LOCK_PR or CHANT_UNLOCK_PR set, as the apply before merge does.
+  const targetBranch = loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH";
+  const commentLocks = prCommentLockJobs("gitlab", loop).map((job) => ({
+    job,
+    name: named(job.jobName),
+    rule: `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $${job.gitlabVar} =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == ${targetBranch}`,
+  }));
+  // #4620: `/<product> <plan word>`: a pipeline of the target branch started with CHANT_PREVIEW_PR set previews the merge request's head again.
+  const preview = prCommentPreviewJob("gitlab", env, loop, member?.name);
+  const previewRule = preview ? `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $${preview.gitlabVar} =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == ${targetBranch}` : undefined;
+  const previewName = preview ? named(preview.jobName) : undefined;
+  const previewNoteName = preview ? named(preview.noteJobName) : undefined;
+  // #4628: a push to the target branch marks the open merge requests' notes posted against another commit stale.
+  const stale = prStaleJob("gitlab", env, loop, member?.name);
+  const staleName = stale ? named(PR_STALE_JOB) : undefined;
+  const stages = ["plan", PR_PLAN_NOTE_JOB, ...(stale ? [PR_STALE_JOB] : []), ...commentLocks.map((c) => c.job.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...applies.map((a) => a.stage), ...(control ? [control.name] : []), ...(prEnv ? [PR_ENV_STAGE, PR_ENV_POST_STAGE] : [])];
   const noteJob = named(PR_PLAN_NOTE_JOB);
-  const post = prLoopPostJob("gitlab", env, member?.name);
+  const post = prLoopPostJob("gitlab", env, member?.name, loop.words ? { ...(loop.words.bin ? { bin: loop.words.bin } : {}) } : undefined, { ...(loop.staleNotes ? { staleNotes: true } : {}), ...(loop.respond ? { respond: loop.respond } : {}), ...(loop.decide ? { decide: loop.decide } : {}) });
+  // #4619: with a control repo named, the note job reads its chant/lifecycle, read-only, so pr-post marks the cross-stack edges.
+  const controlRead = loop.control ? controlNoteCheckout("gitlab", loop.control.target, loop.words ?? {}) : undefined;
   const doc: Record<string, unknown> = {
     // Included files merge their top-level keys, so a member's file carries
     // the rules every member shares and no name: two names would collide.
-    workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, { if: onPlanNotes }, ...(greens.length > 0 ? [{ if: onGreen }] : []), ...(prEnv ? [{ if: GITLAB_SCHEDULE_RULE }] : [])] },
+    workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, { if: onPlanNotes }, ...(greens.length > 0 ? [{ if: onGreen }] : []), ...commentLocks.map((c) => ({ if: c.rule })), ...(previewRule ? [{ if: previewRule }] : []), ...(prEnv ? [{ if: GITLAB_SCHEDULE_RULE }] : [])] },
     stages,
     variables: { ...options.variables, CHANT_ENV: env, ...GITLAB_FULL_HISTORY },
     [planJob]: {
@@ -423,7 +469,7 @@ function prLoopGitlabPipeline(
       variables: { ...plan.run.env, ...tradeVars(identity?.plan) },
       // #4295: the merge request's code runs in this job, so the job's shell drops the forge tokens first.
       // #4296: with identity, the trade runs before that, and the same unset drops the token variables too.
-      script: [...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]), ...script(plan)],
+      script: [...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]), ...dropControl, ...script(plan)],
       artifacts: { when: "always", paths: [reportPath] },
     },
     // #4295, #4328: a job of the target branch's pipeline posts each open merge request's note and status from its plan job's report.
@@ -431,8 +477,62 @@ function prLoopGitlabPipeline(
       stage: PR_PLAN_NOTE_JOB,
       image,
       rules: [{ if: onPlanNotes }],
-      script: [...enter, ...beforeScript, post.command],
+      ...(Object.keys(post.env).length > 0 ? { variables: post.env } : {}),
+      script: [...enter, ...beforeScript, ...(controlRead ? [controlRead.script] : []), post.command],
     },
+    ...(stale && staleName
+      ? {
+          // The pushed commit of the target branch: none of a merge request's code is here.
+          [staleName]: { stage: PR_STALE_JOB, image, rules: [{ if: onMerge }], variables: stale.env, script: [...enter, ...beforeScript, stale.command] },
+        }
+      : {}),
+    ...Object.fromEntries(
+      commentLocks.map(({ job, name, rule }) => [
+        name,
+        // The target branch's commit, so none of the merge request's code runs here.
+        { stage: job.jobName, image, rules: [{ if: rule }], variables: job.env, script: [...enter, ...beforeScript, job.line] },
+      ]),
+    ),
+    ...(preview && previewName && previewNoteName && previewRule
+      ? {
+          [previewName]: {
+            stage: preview.jobName,
+            image,
+            rules: [{ if: previewRule }],
+            ...trading(identity?.plan),
+            variables: { ...preview.plan.run.env, ...tradeVars(identity?.plan) },
+            // A pipeline of the target branch holds the protected tokens, so the job drops them before it checks out the merge request's head.
+            script: [
+              ...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]),
+              ...dropControl,
+              "unset CHANT_RUNNER_KEY",
+              ...("line" in preview.head ? [preview.head.line] : []),
+              // The ledger while the clone can still fetch it: the plan reads the gate ledger from the local branch.
+              "git fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true",
+              // The runner's clone keeps the job token in origin's URL; the merge request's code never sees it.
+              GITLAB_SCRUB_ORIGIN,
+              preview.base,
+              ...prLoopSetup(image, loop.engineSetup),
+              ...enter,
+              ...beforeScript,
+              ...(preview.plan.setup ?? []),
+              ...(preview.plan.build ?? []),
+              preview.plan.run.command,
+              ...extraScript,
+            ],
+            artifacts: { when: "always", paths: [reportPath] },
+          },
+          [previewNoteName]: {
+            stage: preview.noteJobName,
+            image,
+            needs: [{ job: previewName, artifacts: true }],
+            rules: [{ if: previewRule, when: "always" }],
+            variables: preview.post.env,
+            // The target branch's commit: the job's own clone, where none of the merge request's code runs.
+            script: [...enter, ...beforeScript, ...(controlRead ? [controlRead.script] : []), ...(preview.post.setup ?? []), preview.post.command],
+          },
+        }
+      : {}),
     ...Object.fromEntries(
       applies.map(({ job, name, stage }, i) => [
         name,
@@ -440,7 +540,8 @@ function prLoopGitlabPipeline(
           stage,
           image,
           ...(i > 1 ? { needs: [applies[i - 1]!.name] } : {}),
-          resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : prApplyGroup(env, member?.name),
+          // #4552: on the repo grain every apply of the repository shares one resource group.
+          resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : loop.lockGrain === "repo" ? REPO_APPLY_GROUP : prApplyGroup(env, member?.name),
           // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
           rules: [{ if: job.jobName === "record" ? onMerge : onGreen, ...(job.wave && i > 1 ? { when: "always" } : {}) }],
           ...trading(applySpec(job)),
@@ -462,20 +563,53 @@ function prLoopGitlabPipeline(
         },
       ]),
     ),
+    ...(control && controlJob
+      ? {
+          [controlJob]: {
+            stage: control.name,
+            image,
+            needs: [lastGreen],
+            rules: [{ if: onGreen }],
+            // The runner sets a needed job's dotenv values when the script starts, so the commit is read there.
+            script: [
+              ...Object.entries(control.env).map(([k, v]) => `export ${k}="${v}"`),
+              `bash <<'CONTROL_DISPATCH' || exit $?\n${control.script}\nCONTROL_DISPATCH`,
+            ],
+          },
+        }
+      : {}),
   ...(prEnv ? prEnv.jobs : {}),
   };
   const jobs: GeneratedJob[] = [
     { jobName: planJob, component: "merge request plan", stage: "plan", needs: [] },
     { jobName: noteJob, component: "merge request plan note", stage: PR_PLAN_NOTE_JOB, needs: [] },
+    ...(stale && staleName ? [{ jobName: staleName, component: "merge request stale notes", stage: PR_STALE_JOB, needs: [] }] : []),
+    ...commentLocks.map(({ job, name }) => ({ jobName: name, component: `merge request ${job.command} comment`, stage: job.jobName, needs: [] })),
+    ...(preview && previewName && previewNoteName
+      ? [
+          { jobName: previewName, component: "merge request preview comment", stage: preview.jobName, needs: [] },
+          { jobName: previewNoteName, component: "merge request preview comment note", stage: preview.noteJobName, needs: [previewName] },
+        ]
+      : []),
     ...applies.map(({ job, name, stage }, i) => ({
       jobName: name,
       component: job.wave ? `green apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : "green apply",
       stage,
       needs: i > 1 ? [applies[i - 1]!.name] : [],
     })),
+    ...(controlJob ? [{ jobName: controlJob, component: "control repo dispatch", stage: control!.name, needs: [lastGreen!] }] : []),
     ...(prEnv ? prEnv.listed : []),
   ];
-  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...applies.map((a) => a.name), ...Object.keys(prEnv?.jobs ?? {})].map((key) => [key, doc[key]] as const));
+  // #4625: each job on its stage's runner tags, the plan side's, the apply side's, or the default.
+  if (loop.runners) {
+    for (const stage of ["plan", "apply", "default"] as const) assertRunnerLabels("The merge-request pipeline", `runners.${stage}`, loop.runners[stage], "GitLab");
+    for (const job of jobs) {
+      const tags = gitlabTags(prLoopRunner(loop, prLoopJobStage(job.jobName, member?.name)));
+      const entry = doc[job.jobName] as Record<string, unknown> | undefined;
+      if (tags && entry) doc[job.jobName] = { ...entry, tags };
+    }
+  }
+  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...(staleName ? [staleName] : []), ...commentLocks.map((c) => c.name), ...(previewName && previewNoteName ? [previewName, previewNoteName] : []), ...applies.map((a) => a.name), ...(controlJob ? [controlJob] : []), ...Object.keys(prEnv?.jobs ?? {})].map((key) => [key, doc[key]] as const));
   return { yaml, stages, jobs, env };
 }
 
@@ -511,7 +645,7 @@ function prEnvGitlabJobs(
   const reportPath = member ? memberRepoPath(member, PR_ENV_REPORT_DIR) : PR_ENV_REPORT_DIR;
   const environment = "pr-$CI_MERGE_REQUEST_IID";
   const group = `chant-pr-env-${member ? `${member.name}-` : ""}$CI_MERGE_REQUEST_IID`;
-  const script = (j: typeof up): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(j.build ?? []), j.command, ...extraScript];
+  const script = (j: typeof up): string[] => [...prLoopSetup(image, loop.engineSetup), ...enter, ...beforeScript, ...(j.build ?? []), j.command, ...extraScript];
   const artifacts = { when: "always", paths: [reportPath] };
   // #4330: env-up, env-down and env-sweep trade the job's OIDC token for the pull request environments' identity first.
   const identity = loop.prEnvIdentity;

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

@@ -0,0 +1,43 @@
+/**
+ * `/<product> lock` and `/<product> unlock` on GitLab (#4588). GitLab starts
+ * no pipeline on a note, so each job runs in a pipeline of the target
+ * branch started with CHANT_LOCK_PR or CHANT_UNLOCK_PR set to the merge
+ * request's iid, as the apply before merge does with CHANT_APPLY_PR.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+const WORDS = { product: "plywood", commands: { lock: "lock" as const, unlock: "unlock" as const }, bin: "npx --no-install plywood" };
+
+interface Job { stage: string; rules: Array<{ if: string }>; variables: Record<string, string>; script: string[] }
+type Doc = { workflow: { rules: Array<{ if: string }> }; stages: string[] } & Record<string, Job>;
+
+describe("the GitLab pipeline's lock and unlock comments", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { locks: "plan", words: WORDS } }).yaml) as Doc;
+  const LOCK = '$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $CHANT_LOCK_PR =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH';
+
+  test("each job runs in a target-branch pipeline started with its variable", () => {
+    expect(doc["comment-lock"]!.rules).toEqual([{ if: LOCK }]);
+    expect(doc.workflow.rules.map((r) => r.if)).toContain(LOCK);
+    expect(doc["comment-unlock"]!.rules[0]!.if).toContain("$CHANT_UNLOCK_PR");
+    expect(doc.stages).toEqual(expect.arrayContaining(["comment-lock", "comment-unlock"]));
+  });
+
+  test("the merge request's iid comes from the variable, and the lines run the product's bin", () => {
+    expect(doc["comment-lock"]!.variables).toEqual({ PR_NUMBER: "$CHANT_LOCK_PR" });
+    expect(doc["comment-lock"]!.script.at(-1)).toBe('npx --no-install plywood lock --keep --pr "$PR_NUMBER" --forge gitlab');
+    expect(doc["comment-unlock"]!.script.at(-1)).toBe('npx --no-install plywood unlock --pr "$PR_NUMBER"');
+  });
+
+  test("neither job without ci.locks", () => {
+    const plain = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { words: WORDS } }).yaml) as Doc;
+    expect(plain["comment-lock"]).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,61 @@
+/**
+ * The preview comment on GitLab (#4620). GitLab starts no pipeline on a
+ * note, so both jobs run in a pipeline of the target branch started with
+ * CHANT_PREVIEW_PR set to the merge request's iid. The preview job drops the
+ * protected tokens and origin's credentials before the merge request's code
+ * runs; the note job posts from its own clone.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+interface Job { stage: string; rules: Array<{ if: string; when?: string }>; needs?: unknown[]; variables: Record<string, string>; script: string[] }
+type Doc = { workflow: { rules: Array<{ if: string }> }; stages: string[] } & Record<string, Job>;
+
+describe("the GitLab pipeline's preview comment", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { previewComment: true, words: WORDS } }).yaml) as Doc;
+  const RULE = '$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $CHANT_PREVIEW_PR =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH';
+  const preview = doc["comment-preview"]!;
+  const note = doc["comment-preview-note"]!;
+
+  test("both jobs run in a target-branch pipeline started with CHANT_PREVIEW_PR", () => {
+    expect(preview.rules).toEqual([{ if: RULE }]);
+    expect(note.rules).toEqual([{ if: RULE, when: "always" }]);
+    expect(doc.workflow.rules.map((r) => r.if)).toContain(RULE);
+    expect(doc.stages).toEqual(expect.arrayContaining(["comment-preview", "comment-preview-note"]));
+  });
+
+  test("the preview job drops the tokens, then checks out the head and scrubs origin before any of its code runs", () => {
+    const script = preview.script;
+    const drop = script.findIndex((l) => l.startsWith("unset CHANT_FORGE_TOKEN"));
+    const head = script.findIndex((l) => l.includes("refs/merge-requests/$PR_NUMBER/head"));
+    const scrub = script.findIndex((l) => l.startsWith("git remote set-url origin"));
+    const plan = script.findIndex((l) => l.includes("plywood ci run plan"));
+    expect(drop).toBeGreaterThanOrEqual(0);
+    expect(script).toContain("unset CHANT_RUNNER_KEY");
+    expect(drop).toBeLessThan(head);
+    expect(head).toBeLessThan(scrub);
+    expect(scrub).toBeLessThan(plan);
+    expect(preview.variables.PR_NUMBER).toBe("$CHANT_PREVIEW_PR");
+    expect(preview.variables.BASE_SHA).toBe("$CI_COMMIT_SHA");
+  });
+
+  test("the note job finds the head again and posts for that merge request", () => {
+    expect(note.variables).toEqual({ PR_NUMBER: "$CHANT_PREVIEW_PR" });
+    expect(note.script.some((l) => l.includes("git ls-remote origin"))).toBe(true);
+    expect(note.script.at(-1)).toBe('npx --no-install plywood components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge gitlab');
+  });
+
+  test("no preview job without previewComment", () => {
+    const plain = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { words: WORDS } }).yaml) as Doc;
+    expect(plain["comment-preview"]).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,20 @@
+/**
+ * The preview comment's --target on GitLab (#4626): the preview job runs
+ * `pr-plan --comment-targets`, which reads CHANT_PREVIEW_COMMENT, a variable
+ * of the target-branch pipeline. Written for the ci-products post-merge pass.
+ */
+import { expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+test("the preview job runs pr-plan --comment-targets (#4626)", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { previewComment: true, words: WORDS } }).yaml) as Record<string, { script: string[]; variables: Record<string, string> }>;
+  const preview = doc["comment-preview"]!;
+  expect(preview.script.join("\n")).toContain("--comment-targets");
+  expect(preview.variables).not.toHaveProperty("CHANT_PREVIEW_COMMENT");
+  expect(doc.plan!.script.join("\n")).not.toContain("--comment-targets");
+});