@intentius/chant-lexicon-gitlab 0.124.54 → 0.124.55

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

@@ -37,6 +37,18 @@
  * 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).
  */
 
 import {
@@ -55,14 +67,25 @@ 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,
+  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 { emitGitlabFile } from "./ci-jobs";
 
 /** 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) => {
@@ -87,6 +110,10 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
 
   const byReview = spec.waves.some((w) => w.approval === "pr-review");
   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 +127,7 @@ 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(" ")],
       },
     ]);
   }
@@ -126,13 +153,48 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
         variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}), ...(group?.variables ?? {}), ...(cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(cloud) } : {}) },
         rules,
         ...(job.needs.length > 0 ? { needs: job.needs } : {}),
-        script: [...(cloud ? gitlabTradeLines() : []), ...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
+        script: [...(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.
         allow_failure: { exit_codes: [1] },
         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 +203,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(" ")],
       },
     ]);
   }
@@ -153,6 +215,7 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
     ...(spec.resume
       ? [`# The ${spec.name}-resume job retries it for you in a pipeline schedule; give the schedule the cron "${spec.resume.schedule}".`]
       : []),
+    ...(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

@@ -61,11 +61,15 @@ import {
   prLoopWaveJobs,
   prLoopWithWaves,
   prEnvJobs,
+  prCommentLockJobs,
+  prCommentPreviewJob,
   PR_ENV_REPORT_DIR,
   PR_ENV_POST_JOB,
 } 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 +362,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 +404,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 +413,43 @@ 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;
+  const stages = ["plan", PR_PLAN_NOTE_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);
+  // #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 +460,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 +468,55 @@ function prLoopGitlabPipeline(
       stage: PR_PLAN_NOTE_JOB,
       image,
       rules: [{ if: onPlanNotes }],
-      script: [...enter, ...beforeScript, post.command],
+      script: [...enter, ...beforeScript, ...(controlRead ? [controlRead.script] : []), post.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 +524,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 +547,43 @@ 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: [] },
+    ...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));
+  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...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 +619,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.control.test.ts

@@ -0,0 +1,81 @@
+/**
+ * #4568: with a control repo, the GitLab merge-request pipeline adds a
+ * `control-dispatch` job after the last apply on merge, and the plan job
+ * unsets the control repo's token variables with the forge tokens, since a
+ * CI/CD variable reaches every job. The control repo's own pipeline runs on
+ * a trigger. Generated YAML only; the request is tested against fake forges
+ * in packages/core/src/control/control.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { resolveControlTarget } from "@intentius/chant/control/dispatch";
+import { generateGitlabPipeline } from "./generate-pipeline";
+import { generateControlPipeline } from "./control-pipeline";
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({ name, dependsOn, deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"])];
+const control = { target: resolveControlTarget({ repo: "gitlab.com/acme/control", op: "deploy", tokenSecret: "TERRAGUCCI_CONTROL_TOKEN" }, "network") };
+
+interface Job {
+  stage: string;
+  needs?: string[];
+  rules: Array<{ if: string }>;
+  script: string[];
+  resource_group?: string;
+}
+
+describe("the GitLab pipeline's control dispatch (#4568)", () => {
+  test("one job after the apply, and the plan job drops the token variables", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control, words: { product: "terragucci" } } });
+    const doc = parseYAML(yaml) as Record<string, Job> & { stages: string[] };
+    const job = doc["control-dispatch"]!;
+    expect(job.needs).toEqual(["apply"]);
+    expect(doc.stages.at(-1)).toBe("control-dispatch");
+    expect(job.script[0]).toBe('export CHANT_CONTROL_SHA="$CI_COMMIT_SHA"');
+    expect(job.script[1]).toContain('CHANT_CONTROL_TOKEN="${TERRAGUCCI_CONTROL_TOKEN:-}"');
+    expect(job.script[1]).toContain("/trigger/pipeline");
+    expect(doc.plan!.script.some((l) => l.startsWith("unset ") && l.includes("TERRAGUCCI_CONTROL_TOKEN") && l.includes("CHANT_CONTROL_TOKEN"))).toBe(true);
+  });
+
+  test("with a gate per wave, the job follows the last wave and reads its GREEN_SHA", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control }, gatedWaves: { gate: "release" } });
+    const doc = parseYAML(yaml) as Record<string, Job>;
+    expect(doc["control-dispatch"]!.needs).toEqual(["apply-wave-2"]);
+    expect(doc["control-dispatch"]!.script[0]).toBe('export CHANT_CONTROL_SHA="$GREEN_SHA"');
+  });
+});
+
+describe("the control repo's pipeline on GitLab (#4568)", () => {
+  test("a trigger with the member and Op runs the dependents, one member at a time", () => {
+    const file = generateControlPipeline({ words: { product: "terragucci" } });
+    expect(file.path).toBe(".gitlab/terragucci-dependents.yml");
+    const doc = parseYAML(file.content) as Record<string, Job>;
+    expect(doc.dependents!.rules[0]!.if).toBe('$CI_PIPELINE_SOURCE == "trigger" && $CHANT_CONTROL_MEMBER && $CHANT_CONTROL_OP');
+    expect(doc.dependents!.resource_group).toBe("terragucci-dependents-$CHANT_CONTROL_MEMBER");
+    expect(doc.dependents!.script[0]).toContain("workspace run --dependents-of");
+  });
+});
+
+// #4619: the note job reads the control repo, read-only, so the note marks the cross-stack edges.
+describe("the GitLab plan-note job's read of the control repo (#4619)", () => {
+  test("fetches the control repo's chant/lifecycle before it posts, and exports CHANT_CONTROL_DIR", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control, words: { product: "terragucci" } } });
+    const doc = parseYAML(yaml) as Record<string, Job>;
+    const script = doc["plan-note"]!.script;
+    const read = script.findIndex((l) => l.includes("refs/heads/chant/lifecycle"));
+    expect(read).toBeGreaterThan(-1);
+    expect(script[read + 1]).toContain("components pr-post");
+    expect(script[read]).toContain('CHANT_CONTROL_READ_TOKEN="${CHANT_CONTROL_READ_TOKEN:-}"');
+    expect(script[read]).toContain('export CHANT_CONTROL_DIR="$chant_control_dir"');
+    expect(script[read]).toContain("'https://gitlab.com/acme/control.git'");
+    // The dispatch token is not the note job's.
+    expect(script[read]).not.toContain("TERRAGUCCI_CONTROL_TOKEN");
+  });
+
+  test("without a control repo the note job reads none", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } });
+    expect(yaml).not.toContain("CHANT_CONTROL_DIR");
+  });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * #4549: with a Pulumi Cloud identity, the merge-request pipeline's plan and
+ * record jobs trade their `id_tokens` for a preview token and the apply job
+ * for an up token. No job reads a Pulumi token from a CI/CD variable, and
+ * the plan job names no up token. Generated YAML only; the trade itself is
+ * tested against the fake exchange in packages/core/src/ci-identity-pulumi.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { gitlabTradeLines, resolveCloudIdentity, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
+import { FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] }];
+
+const IDENTITY = resolveCloudIdentity({ pulumi: { organization: "acme", rules: [{ plan: "team:preview", apply: "team:deploy" }] } }, "prod")!;
+
+interface GitlabJob {
+  id_tokens?: Record<string, { aud: string }>;
+  variables?: Record<string, string>;
+  script: string[];
+}
+
+describe("the GitLab pipeline's Pulumi Cloud tokens (#4549)", () => {
+  const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: { applyOnMerge: true, identity: IDENTITY } });
+  const doc = parseYAML(yaml) as Record<string, GitlabJob>;
+
+  test("the plan job asks for the Pulumi id token and trades for the preview token before anything else", () => {
+    expect(doc.plan!.id_tokens).toEqual({ CHANT_ID_TOKEN_PULUMI: { aud: "urn:pulumi:org:acme" } });
+    expect(doc.plan!.script.slice(0, 3)).toEqual(gitlabTradeLines(FORGE_TOKEN_VARS));
+    expect(JSON.parse(doc.plan!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.plan);
+  });
+
+  test("the record job takes the preview token and the apply job the up token", () => {
+    expect(JSON.parse(doc.record!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.plan);
+    expect(JSON.parse(doc.apply!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.apply);
+    expect(doc.apply!.id_tokens).toEqual(doc.plan!.id_tokens);
+  });
+
+  test("the plan job names no up token, and nothing reads PULUMI_ACCESS_TOKEN from a CI/CD variable", () => {
+    expect(JSON.stringify(doc.plan)).not.toContain("team:deploy");
+    expect(yaml).not.toContain("$PULUMI_ACCESS_TOKEN");
+  });
+});