@intentius/chant-lexicon-gitlab 0.124.55 → 0.124.57

package/dist/components/generate-op-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAiBH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAQlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AA4HhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAwMxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAiBH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAUlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AA4HhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CA6OxB"}

package/dist/components/generate-op-pipeline.js

@@ -120,6 +120,8 @@ import { assertReviewSplit, GITLAB_REVIEW_NOTES_VAR, gitlabReviewJobs, REVIEW_DI
 import { AGENT_DIR, resolveAgentSpec } from "@intentius/chant/ci-agent";
 import { activeProductWords } from "@intentius/chant/ci-product-words";
 import { gitlabAgentHeader, gitlabAgentJobs, gitlabAgentPushJobName, gitlabDriftArtifacts, gitlabDriftRunLines } from "./agent-jobs.js";
+import { assertScheduledOpCloud, scheduledOpUpdateJobName } from "@intentius/chant/scheduled-op-cloud";
+import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
 /**
  * Default stage every generated job runs in, and the default base of the
  * generated file's name (#2293). Overridable via `options.opsStage` (and the
@@ -247,6 +249,11 @@ export function generateGitlabOpPipeline(ops, options = {}) {
     const words = activeProductWords();
     for (const spec of ops) {
         const subject = `Scheduled Op "${spec.name}"`;
+        // #4631: the job's cloud identities and the update on drift, checked before anything renders.
+        assertScheduledOpCloud(spec);
+        if (spec.update?.permissions && Object.keys(spec.update.permissions).length > 0) {
+            throw new Error(`${subject}: update.permissions has no GitLab form; a GitLab job's token scopes are the project's (contents: write included: whether a job token may push is a project setting), and its cloud identity is update.cloud.`);
+        }
         // #4616: GitLab picks a runner by tags.
         assertRunnerLabels(subject, "runner", spec.runner, "GitLab");
         const tags = gitlabTags(spec.runner);
@@ -273,7 +280,10 @@ export function generateGitlabOpPipeline(ops, options = {}) {
             noteJobs.push(pushName);
             continue;
         }
-        const idTokens = gitlabIdTokens(spec.name, spec.permissions);
+        const declaredIdTokens = gitlabIdTokens(spec.name, spec.permissions);
+        // #4631: a cloud trade takes an id token per cloud, beside the ones the spec declares.
+        const idTokens = spec.cloud ? { ...(declaredIdTokens ?? {}), ...gitlabTradeIdTokens(spec.cloud) } : declaredIdTokens;
+        const update = spec.update;
         const findingMode = spec.findingMode ?? "report";
         const trigger = resolveOpTrigger(spec);
         assertTriggerSupportsMode(spec.name, findingMode, trigger);
@@ -313,6 +323,7 @@ export function generateGitlabOpPipeline(ops, options = {}) {
         // than a caller being able to repoint the gate block's own artifact path.
         const jobVariables = {
             ...(spec.variables ?? {}),
+            ...(spec.cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(spec.cloud) } : {}),
             ...(gated ? { [GATE_SUMMARY_VAR]: gateSummary } : {}),
         };
         const rulesFor = changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules;
@@ -335,7 +346,10 @@ export function generateGitlabOpPipeline(ops, options = {}) {
             noteJobs.push(noteName);
             continue;
         }
-        const runLines = driftAgent ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
+        // #4631: an update follows a drift check the same way the drift agent does, on the dotenv the run leaves.
+        const flagsDrift = driftAgent !== undefined || update !== undefined;
+        const runLines = flagsDrift ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
+        const driftDir = member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR;
         doc[jobName] = {
             stage,
             image,
@@ -347,17 +361,42 @@ export function generateGitlabOpPipeline(ops, options = {}) {
             ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
             ...nonEmpty("variables", jobVariables),
             rules: rulesFor,
-            script: [...cdLine, ...setupScript, ...beforeScript, ...runLines, ...extraScript],
+            // #4631: the trade first, before any line of the checkout's code runs, and the token variables unset by it.
+            script: [...(spec.cloud ? gitlabTradeLines() : []), ...cdLine, ...setupScript, ...beforeScript, ...runLines, ...extraScript],
             // `when: always` because the run this publishes for is the green one: a
             // gated apply succeeds, and the block is the only thing that says a
             // human still has to act. A run that walked through its gate writes no
             // block, and GitLab reports the empty upload as a warning, not a failure.
             ...(gated
                 ? { artifacts: { when: "always", paths: [member ? memberRepoPath(member, gateSummary) : gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
-                : driftAgent
-                    ? { artifacts: gitlabDriftArtifacts(member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR) }
+                : flagsDrift
+                    ? { artifacts: gitlabDriftArtifacts(driftDir) }
                     : {}),
         };
+        if (update) {
+            // #4631: the update's own job, which alone holds the update's identity, after a run that found drift.
+            const name = scheduledOpUpdateJobName(jobName);
+            opLines.push(`#     update: ${name} runs \`${update.command}\` when ${jobName} exits with chant's drift code${update.cloud ? ", holding its own cloud identity" : ""}`);
+            doc[name] = {
+                stage,
+                image,
+                ...(tags ? { tags } : {}),
+                needs: [{ job: jobName, artifacts: true }],
+                ...(update.cloud ? { id_tokens: gitlabTradeIdTokens(update.cloud) } : {}),
+                ...(update.environment ? { environment: environmentDoc(update.environment) } : {}),
+                ...nonEmpty("variables", { ...(update.variables ?? {}), ...(update.cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(update.cloud) } : {}) }),
+                rules: rulesFor.map((r) => ({ ...r, when: "always" })),
+                script: [
+                    `if [ "\${CHANT_AGENT_DRIFT:-0}" != "1" ]; then echo "no drift, so the update does not run"; exit 0; fi`,
+                    ...(update.cloud ? gitlabTradeLines() : []),
+                    ...cdLine,
+                    ...setupScript,
+                    ...beforeScript,
+                    update.command,
+                ],
+            };
+            noteJobs.push(name);
+        }
         if (driftAgent) {
             const name = `${jobName}-agent`;
             opLines.push(...gitlabAgentHeader(name, driftAgent, spec.agent?.tokenEnv));

package/dist/components/generate-op-waves-pipeline.d.ts

@@ -18,14 +18,23 @@
  * A wave's `environment` is the job's own `environment:`; protect it in the
  * project settings to put a reviewer in front of the job as well.
  *
+ * The wave jobs carry no `resource_group` (ruling for ci-products
+ * 2026-10-28, "Ledger lock"), the same as the GitHub and Forgejo waves files
+ * carry no concurrency group: a per-wave resource group would keep two
+ * pipelines' plunge stacks apart where their resource rows do not meet. A
+ * stock Pulumi stack or a Terraform root waits for its row on chant's ledger,
+ * oldest commit first, up to the job's `timeout`, which `CHANT_LOCK_WAIT`
+ * sits five minutes under; the project's own maximum timeout still caps it.
+ *
  * With `resume` on the spec (#3683), a `<name>-resume` job runs `chant run
  * resume --op <name>` in scheduled pipelines only: create a pipeline schedule
  * with the spec's cron. It retries a waiting wave's job once its approval
  * 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
@@ -49,9 +58,19 @@
  * 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 { type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
+/** 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 declare const OP_WAVE_ALLOWED_EXIT: 1;
 /** Render an Op waves spec as one GitLab CI file, `<name>.gitlab-ci.yml` unless `opsFileName` names another. */
 export declare function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult;
 //# sourceMappingURL=generate-op-waves-pipeline.d.ts.map

package/dist/components/generate-op-waves-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAkBH,OAAO,EASL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAI9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAuIvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAkBH,OAAO,EAaL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAO9F,yHAAyH;AACzH,eAAO,MAAM,oBAAoB,GAAoB,CAAC;AAEtD,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAuKvH"}

package/dist/components/generate-op-waves-pipeline.js

@@ -18,14 +18,23 @@
  * A wave's `environment` is the job's own `environment:`; protect it in the
  * project settings to put a reviewer in front of the job as well.
  *
+ * The wave jobs carry no `resource_group` (ruling for ci-products
+ * 2026-10-28, "Ledger lock"), the same as the GitHub and Forgejo waves files
+ * carry no concurrency group: a per-wave resource group would keep two
+ * pipelines' plunge stacks apart where their resource rows do not meet. A
+ * stock Pulumi stack or a Terraform root waits for its row on chant's ledger,
+ * oldest commit first, up to the job's `timeout`, which `CHANT_LOCK_WAIT`
+ * sits five minutes under; the project's own maximum timeout still caps it.
+ *
  * With `resume` on the spec (#3683), a `<name>-resume` job runs `chant run
  * resume --op <name>` in scheduled pipelines only: create a pipeline schedule
  * with the spec's cron. It retries a waiting wave's job once its approval
  * 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
@@ -49,12 +58,25 @@
  * 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 { assertGitlabBranch, assertGitlabEnvironment, assertRunnerLabels, CI_IMAGE, environmentDoc, GITLAB_FULL_HISTORY, GITLAB_MERGE_REQUEST_SOURCE, GITLAB_SCHEDULE_SOURCE, gitlabIdTokensDoc, gitlabPushRule, gitlabSetupScript, gitlabTags, nonEmpty, pushBranches, } from "@intentius/chant/ci-jobs";
-import { opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesControlTarget, opWavesLastJobs, opWavesOutcomeCommand, opWavesRecordPlansCommand, opWavesResumeCommand, } from "@intentius/chant/op/op-waves";
+import { opWaveGroupOf, opWaveJobs, opWaveJobTimeout, opWaveOutcomeDir, opWavesControlTarget, opWavesLastJobs, OP_WAVES_APPROVAL_STATUS_VAR, opWavesApprovalStatusCommand, opWavesPostsApprovalStatus, opWavesOutcomeCommand, opWavesRecordPlansCommand, opWavesResumeCommand, } from "@intentius/chant/op/op-waves";
 import { CONTROL_OUTCOME_VAR, CONTROL_TOKEN_VARS, controlDispatchJob } from "@intentius/chant/control/dispatch";
 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.js";
+/** 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, options) {
     const jobs = opWaveJobs(spec, options.specFile, { bin: options.bin });
@@ -82,7 +104,9 @@ export function generateGitlabOpWavesPipeline(spec, options) {
         }
     }
     const specTags = gitlabTags(spec.runner);
-    const byReview = spec.waves.some((w) => w.approval === "pr-review");
+    const product = resolveProductWords(options.words ?? {}).product;
+    // #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;
@@ -92,6 +116,8 @@ export function generateGitlabOpWavesPipeline(spec, options) {
     if (spec.resume)
         stages.push("resume");
     const entries = [["stages", stages]];
+    // The ruling for ci-products (2026-10-28): each wave job's timeout, and the lock wait five minutes under it.
+    const timeout = opWaveJobTimeout(options.jobTimeoutMinutes);
     const variables = nonEmpty("variables", options.variables).variables;
     if (variables)
         entries.push(["variables", variables]);
@@ -107,6 +133,18 @@ export function generateGitlabOpWavesPipeline(spec, options) {
                 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(" ")],
+            },
+        ]);
     }
     for (const job of jobs) {
         const wave = spec.waves[job.wave - 1];
@@ -118,21 +156,32 @@ export function generateGitlabOpWavesPipeline(spec, options) {
         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,
             {
                 stage: stages[job.wave - 1 + (byReview ? 1 : 0)],
                 image,
                 ...(tags ? { tags } : {}),
-                resource_group: `${spec.name}-${wave.name}`,
+                timeout: `${timeout.minutes} minutes`,
                 ...(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, ...timeout.env, ...(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() : []), ...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] },
+                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" },
             },
         ]);
@@ -188,10 +237,15 @@ export function generateGitlabOpWavesPipeline(spec, options) {
         `# 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`;

package/dist/components/generate-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAWH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA8BjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAkJtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAaH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAkCjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAkJtB"}

package/dist/components/generate-pipeline.js

@@ -31,11 +31,11 @@
  * demonstration: one generator-option edit reflects in every job without
  * touching the component declarations.
  */
-import { assertGitlabBranch, CI_IMAGE, ciJobName, fillCommand, GITLAB_FULL_HISTORY, GITLAB_MERGE_REQUEST_SOURCE, gitlabPushRule, } from "@intentius/chant/ci-jobs";
+import { assertGitlabBranch, assertRunnerLabels, CI_IMAGE, ciJobName, fillCommand, GITLAB_FULL_HISTORY, GITLAB_MERGE_REQUEST_SOURCE, gitlabPushRule, gitlabTags, } from "@intentius/chant/ci-jobs";
 import { resolveComponentGraph } 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 { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, GITLAB_APPLY_PR_VAR, GITLAB_PLAN_NOTES_VAR, gitlabPlanJobName, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, prCommentLockJobs, prCommentPreviewJob, PR_ENV_REPORT_DIR, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, GITLAB_APPLY_PR_VAR, GITLAB_PLAN_NOTES_VAR, gitlabPlanJobName, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, 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";
@@ -374,9 +374,12 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
     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] : [])];
+    // #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, loop.words ? { ...(loop.words.bin ? { bin: loop.words.bin } : {}) } : undefined);
+    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 = {
@@ -401,8 +404,15 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
             stage: PR_PLAN_NOTE_JOB,
             image,
             rules: [{ if: onPlanNotes }],
+            ...(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.
@@ -496,6 +506,7 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
     const jobs = [
         { 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
             ? [
@@ -512,7 +523,18 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
         ...(controlJob ? [{ jobName: controlJob, component: "control repo dispatch", stage: control.name, needs: [lastGreen] }] : []),
         ...(prEnv ? prEnv.listed : []),
     ];
-    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]]));
+    // #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"])
+            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];
+            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]]));
     return { yaml, stages, jobs, env };
 }
 /** The stage a pull request environment's jobs run in (#4298). */

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "f5a242ce00bc716bcb44314a1301000b9ecad9187d4591c776829885535369e2",
+    "manifest.json": "617558151e681cf5f4ea5df936170cd8ec7739e81744fb3157b8f34f416b02eb",
     "meta.json": "db082fbf90c5941c498b2bee0f106103449c1a4c257716ca2220f0dd490450b2",
     "types/index.d.ts": "a048a66ebe20da0cb5fc889054cac69044d9bf882e2c56b5c5bf113d1f3ba57c",
     "rules/artifact-no-expiry.ts": "0ca5bb972d4a542126e8a0229d43b55658394cb7dd9b9923b2c590bec1c2ad7d",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "91aa3c4a176252cd5cd8ab7f02ecef7274e79a95aa85a1bfc31270ef32021897"
+  "composite": "841ec4d4eec31c0a7724d61da9bf8b8f1592960dde4938b1b9140fe3ec0d9b7b"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.124.55",
+  "version": "0.124.57",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.124.55",
+  "version": "0.124.57",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -67,8 +67,8 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.55",
-    "@intentius/chant-lexicon-github": "^0.124.55"
+    "@intentius/chant": "^0.124.57",
+    "@intentius/chant-lexicon-github": "^0.124.57"
   },
   "peerDependenciesMeta": {
     "@intentius/chant-lexicon-github": {

package/src/components/__golden__/op-waves-jobs.yml

@@ -1,7 +1,9 @@
 # chant Op waves "migrations": 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.
 
 stages:
   - wave-1-dev
@@ -13,12 +15,15 @@ wave-1-dev:
   tags:
     - docker
     - dev
-  resource_group: migrations-dev
+  timeout: '180 minutes'
   variables:
     GIT_DEPTH: '0'
+    CHANT_LOCK_WAIT: '10500'
+    CHANT_JOB_GUARD: '{"forge":"gitlab","job":"wave 1 (dev) of migrations","branches":["main"],"runnerTags":["docker","dev"]}'
   rules:
     - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
   script:
+    - '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
     - chant run wave --spec waves.json --wave 1
   allow_failure:
     exit_codes:
@@ -34,17 +39,20 @@ wave-2-prod-decide:
   image: node:22
   tags:
     - plan
-  resource_group: migrations-prod
+  timeout: '180 minutes'
   id_tokens:
     PLAN_TOKEN:
       aud: plan.example
   variables:
     GIT_DEPTH: '0'
+    CHANT_LOCK_WAIT: '10500'
+    CHANT_JOB_GUARD: '{"forge":"gitlab","job":"the deciding job of wave 2 (prod) of migrations","branches":["main"],"runnerTags":["plan"]}'
   rules:
     - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
   needs:
     - wave-1-dev
   script:
+    - '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
     - chant run wave --spec waves.json --wave 2 --decide
   allow_failure:
     exit_codes:
@@ -61,7 +69,7 @@ wave-2-prod-us:
   image: node:22
   tags:
     - us-apply
-  resource_group: migrations-prod
+  timeout: '180 minutes'
   environment:
     name: prod-us
   id_tokens:
@@ -69,12 +77,15 @@ wave-2-prod-us:
       aud: us.example
   variables:
     GIT_DEPTH: '0'
+    CHANT_LOCK_WAIT: '10500'
     REGION: us
+    CHANT_JOB_GUARD: '{"forge":"gitlab","job":"job group us of wave 2 (prod) of migrations","forgeEnvironment":"prod-us","branches":["main"],"runnerTags":["us-apply"]}'
   rules:
     - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
   needs:
     - wave-2-prod-decide
   script:
+    - '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
     - echo us
     - chant run wave --spec waves.json --wave 2 --group us
   allow_failure:
@@ -91,7 +102,7 @@ wave-2-prod-eu:
   image: node:22
   tags:
     - eu-apply
-  resource_group: migrations-prod
+  timeout: '180 minutes'
   environment:
     name: prod-eu
   id_tokens:
@@ -99,11 +110,14 @@ wave-2-prod-eu:
       aud: eu.example
   variables:
     GIT_DEPTH: '0'
+    CHANT_LOCK_WAIT: '10500'
+    CHANT_JOB_GUARD: '{"forge":"gitlab","job":"job group eu of wave 2 (prod) of migrations","forgeEnvironment":"prod-eu","branches":["main"],"runnerTags":["eu-apply"]}'
   rules:
     - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
   needs:
     - wave-2-prod-decide
   script:
+    - '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
     - chant run wave --spec waves.json --wave 2 --group eu
   allow_failure:
     exit_codes:

package/src/components/generate-op-pipeline.cloud.test.ts

@@ -0,0 +1,40 @@
+/** #4631: a GitLab scheduled Op job trades first, and an update on drift is a job of its own on the run's dotenv. */
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateGitlabOpPipeline } from "./generate-op-pipeline";
+
+interface Job { needs?: unknown; rules?: Array<Record<string, unknown>>; id_tokens?: Record<string, { aud: string }>; variables?: Record<string, string>; script: string[]; artifacts?: Record<string, unknown> }
+
+const PREVIEW = { aws: { role: "arn:aws:iam::1:role/preview", region: "us-east-1", audience: "sts.amazonaws.com" } };
+const UPDATE = { aws: { role: "arn:aws:iam::1:role/update", region: "us-east-1", audience: "sts.amazonaws.com" } };
+const spec: ScheduledOpSpec = { name: "drift-dev", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue", cloud: PREVIEW, update: { command: "plywood up", cloud: UPDATE } };
+
+describe("cloud identities on a GitLab scheduled Op (#4631)", () => {
+  const doc = parseYAML(generateGitlabOpPipeline([spec]).files[0]!.yaml) as unknown as Record<string, Job>;
+  const check = doc["drift-dev"]!;
+  const update = doc["drift-dev-update"]!;
+
+  test("the check's script trades first and unsets the token variables, with an id token per cloud", () => {
+    expect(check.id_tokens).toEqual({ CHANT_ID_TOKEN_AWS: { aud: "sts.amazonaws.com" } });
+    expect(JSON.parse(check.variables!.CHANT_CLOUD_TRADE!)).toEqual(PREVIEW);
+    expect(check.script[0]).toContain("node -e");
+    expect(check.script[1]).toMatch(/^unset .*CHANT_ID_TOKEN_AWS/);
+    expect(check.script.join("\n")).toContain('echo "CHANT_AGENT_DRIFT=1"');
+    expect(check.artifacts).toMatchObject({ reports: { dotenv: ".chant/agent/drift.env" } });
+    expect(JSON.stringify(check)).not.toContain("role/update");
+  });
+
+  test("the update job needs the check, stops with no drift, and trades for its own identity", () => {
+    expect(update.needs).toEqual([{ job: "drift-dev", artifacts: true }]);
+    expect(update.rules!.every((r) => r.when === "always")).toBe(true);
+    expect(update.script[0]).toContain('"${CHANT_AGENT_DRIFT:-0}" != "1"');
+    expect(JSON.parse(update.variables!.CHANT_CLOUD_TRADE!)).toEqual(UPDATE);
+    expect(update.script.at(-1)).toBe("plywood up");
+  });
+
+  test("update.permissions has no GitLab form", () => {
+    expect(() => generateGitlabOpPipeline([{ ...spec, update: { command: "x", permissions: { issues: "write" } } }])).toThrow(/no GitLab form/);
+    expect(() => generateGitlabOpPipeline([{ ...spec, update: { command: "x", permissions: { contents: "write" } } }])).toThrow(/no GitLab form/);
+  });
+});

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

@@ -144,6 +144,8 @@ import { assertReviewSplit, GITLAB_REVIEW_NOTES_VAR, gitlabReviewJobs, REVIEW_DI
 import { AGENT_DIR, resolveAgentSpec } from "@intentius/chant/ci-agent";
 import { activeProductWords } from "@intentius/chant/ci-product-words";
 import { gitlabAgentHeader, gitlabAgentJobs, gitlabAgentPushJobName, gitlabDriftArtifacts, gitlabDriftRunLines } from "./agent-jobs";
+import { assertScheduledOpCloud, scheduledOpUpdateJobName } from "@intentius/chant/scheduled-op-cloud";
+import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
 
 export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
 
@@ -307,6 +309,11 @@ export function generateGitlabOpPipeline(
 
   for (const spec of ops) {
     const subject = `Scheduled Op "${spec.name}"`;
+    // #4631: the job's cloud identities and the update on drift, checked before anything renders.
+    assertScheduledOpCloud(spec);
+    if (spec.update?.permissions && Object.keys(spec.update.permissions).length > 0) {
+      throw new Error(`${subject}: update.permissions has no GitLab form; a GitLab job's token scopes are the project's (contents: write included: whether a job token may push is a project setting), and its cloud identity is update.cloud.`);
+    }
     // #4616: GitLab picks a runner by tags.
     assertRunnerLabels(subject, "runner", spec.runner, "GitLab");
     const tags = gitlabTags(spec.runner);
@@ -333,7 +340,10 @@ export function generateGitlabOpPipeline(
       noteJobs.push(pushName);
       continue;
     }
-    const idTokens = gitlabIdTokens(spec.name, spec.permissions);
+    const declaredIdTokens = gitlabIdTokens(spec.name, spec.permissions);
+    // #4631: a cloud trade takes an id token per cloud, beside the ones the spec declares.
+    const idTokens = spec.cloud ? { ...(declaredIdTokens ?? {}), ...gitlabTradeIdTokens(spec.cloud) } : declaredIdTokens;
+    const update = spec.update;
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
@@ -376,6 +386,7 @@ export function generateGitlabOpPipeline(
     // than a caller being able to repoint the gate block's own artifact path.
     const jobVariables: Record<string, string> = {
       ...(spec.variables ?? {}),
+      ...(spec.cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(spec.cloud) } : {}),
       ...(gated ? { [GATE_SUMMARY_VAR]: gateSummary } : {}),
     };
 
@@ -400,7 +411,10 @@ export function generateGitlabOpPipeline(
       continue;
     }
 
-    const runLines = driftAgent ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
+    // #4631: an update follows a drift check the same way the drift agent does, on the dotenv the run leaves.
+    const flagsDrift = driftAgent !== undefined || update !== undefined;
+    const runLines = flagsDrift ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
+    const driftDir = member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR;
     doc[jobName] = {
       stage,
       image,
@@ -412,17 +426,42 @@ export function generateGitlabOpPipeline(
       ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
       ...nonEmpty("variables", jobVariables),
       rules: rulesFor,
-      script: [...cdLine, ...setupScript, ...beforeScript, ...runLines, ...extraScript],
+      // #4631: the trade first, before any line of the checkout's code runs, and the token variables unset by it.
+      script: [...(spec.cloud ? gitlabTradeLines() : []), ...cdLine, ...setupScript, ...beforeScript, ...runLines, ...extraScript],
       // `when: always` because the run this publishes for is the green one: a
       // gated apply succeeds, and the block is the only thing that says a
       // human still has to act. A run that walked through its gate writes no
       // block, and GitLab reports the empty upload as a warning, not a failure.
       ...(gated
         ? { artifacts: { when: "always", paths: [member ? memberRepoPath(member, gateSummary) : gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
-        : driftAgent
-          ? { artifacts: gitlabDriftArtifacts(member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR) }
+        : flagsDrift
+          ? { artifacts: gitlabDriftArtifacts(driftDir) }
           : {}),
     };
+    if (update) {
+      // #4631: the update's own job, which alone holds the update's identity, after a run that found drift.
+      const name = scheduledOpUpdateJobName(jobName);
+      opLines.push(`#     update: ${name} runs \`${update.command}\` when ${jobName} exits with chant's drift code${update.cloud ? ", holding its own cloud identity" : ""}`);
+      doc[name] = {
+        stage,
+        image,
+        ...(tags ? { tags } : {}),
+        needs: [{ job: jobName, artifacts: true }],
+        ...(update.cloud ? { id_tokens: gitlabTradeIdTokens(update.cloud) } : {}),
+        ...(update.environment ? { environment: environmentDoc(update.environment) } : {}),
+        ...nonEmpty("variables", { ...(update.variables ?? {}), ...(update.cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(update.cloud) } : {}) }),
+        rules: rulesFor.map((r) => ({ ...(r as Record<string, unknown>), when: "always" })),
+        script: [
+          `if [ "\${CHANT_AGENT_DRIFT:-0}" != "1" ]; then echo "no drift, so the update does not run"; exit 0; fi`,
+          ...(update.cloud ? gitlabTradeLines() : []),
+          ...cdLine,
+          ...setupScript,
+          ...beforeScript,
+          update.command,
+        ],
+      };
+      noteJobs.push(name);
+    }
     if (driftAgent) {
       const name = `${jobName}-agent`;
       opLines.push(...gitlabAgentHeader(name, driftAgent, spec.agent?.tokenEnv));

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

@@ -0,0 +1,28 @@
+/** #4630: GitLab approvals start no pipeline, so a schedule posts every open merge request's approval status. */
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGitlabOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "plywood-up",
+  op: "plywood-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pr-review" }],
+};
+
+describe("the approval status job on GitLab (#4630)", () => {
+  test("runs in a schedule that sets CHANT_APPROVAL_STATUS, with --open", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json" }).files[0]!.yaml;
+    expect(yaml).toContain("plywood-up-approval-status:");
+    expect(yaml).toContain('$CI_PIPELINE_SOURCE == "schedule" && $CHANT_APPROVAL_STATUS == "1"');
+    expect(yaml).toContain("chant run wave --spec waves.json --approval-status --open --forge gitlab");
+  });
+
+  test("a pull-request wave records its plans and posts the status too (2026-10-28 ruling)", () => {
+    const pullRequest: OpWavesSpec = { ...spec, waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pull-request" }], approvals: { pullRequest: { gate: "up" } } };
+    const yaml = generateGitlabOpWavesPipeline(pullRequest, { specFile: "waves.json" }).files[0]!.yaml;
+    expect(yaml).toContain("plywood-up-record-plans:");
+    expect(yaml).toContain("plywood-up-approval-status:");
+    expect(yaml).toContain("chant run wave --spec waves.json --approval-status --open --forge gitlab");
+  });
+});

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

@@ -42,7 +42,7 @@ describe("the control dispatch after the last wave on GitLab (#4617)", () => {
 
   test("every wave job and the resume job drop the control repo's token variables first", () => {
     const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
-    expect(yaml).toMatch(/wave-1-canary:[\s\S]*script:\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN\n\s+- npx --no-install plywood run wave --spec waves.json --wave 1/);
+    expect(yaml).toMatch(/wave-1-canary:[\s\S]*script:\n\s+- [^\n]*node -e[^\n]*\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN\n\s+- npx --no-install plywood run wave --spec waves.json --wave 1/);
     expect(yaml).toMatch(/stacks-resume:[\s\S]*script:\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN/);
   });
 

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

@@ -0,0 +1,63 @@
+/**
+ * The apply-job guard in GitLab op-wave jobs (#4624): the script's first
+ * line, before the trade, with the job's expectation in a variable: the
+ * environment, the branches and the runner's tags. Written for the
+ * ci-products post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { spawnSync } from "node:child_process";
+import { JOB_GUARD_ENV, JOB_GUARD_JS } from "@intentius/chant/ci-job-guard";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { generateGitlabOpWavesPipeline, OP_WAVE_ALLOWED_EXIT } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "deploy",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  branches: ["main"],
+  runner: ["deploy"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "prod", runs: [{ target: "prod" }], environment: { name: "production" } },
+  ],
+};
+
+describe("the apply-job guard on GitLab (#4624)", () => {
+  test("the first script line of every wave job", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json", words: { product: "plywood" } }).files[0]!.yaml;
+    for (const job of ["wave-1-dev", "wave-2-prod"]) {
+      const body = yaml.slice(yaml.indexOf(`${job}:`));
+      const script = body.slice(body.indexOf("script:"));
+      expect(script.split("\n")[1]).toContain(JOB_GUARD_JS.slice(0, 40));
+    }
+  });
+
+  test("the variable names the environment, the branches, the tags and the product", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json", words: { product: "plywood" } }).files[0]!.yaml;
+    const prod = yaml.slice(yaml.indexOf("wave-2-prod:"));
+    expect(prod).toContain(JOB_GUARD_ENV);
+    for (const part of ['"forge":"gitlab"', '"forgeEnvironment":"production"', '"branches":["main"]', '"runnerTags":["deploy"]', '"product":"plywood"', '"job":"wave 2 (prod) of deploy"']) {
+      expect(prod).toContain(part);
+    }
+  });
+
+  test("a refused guard fails the job and stops the wave (#4624 ruling: fail hard)", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json", words: { product: "plywood" } }).files[0]!.yaml;
+    const prod = yaml.slice(yaml.indexOf("wave-2-prod:"));
+    expect(prod).toContain(`exit_codes:\n      - ${OP_WAVE_ALLOWED_EXIT}`);
+    const guard = { forge: "gitlab", job: "wave 2 (prod) of deploy", forgeEnvironment: "production", branches: ["main"], runnerTags: ["deploy"] };
+    const r = spawnSync(process.execPath, ["-e", JOB_GUARD_JS], {
+      env: { PATH: process.env.PATH ?? "", [JOB_GUARD_ENV]: JSON.stringify(guard), CI_ENVIRONMENT_NAME: "dev", CI_COMMIT_REF_NAME: "main", CI_COMMIT_REF_PROTECTED: "true", CI_RUNNER_TAGS: "deploy" },
+      encoding: "utf-8",
+    });
+    expect(r.status).toBe(CHANT_EXIT.misplaced);
+    expect(r.status).not.toBe(OP_WAVE_ALLOWED_EXIT);
+  });
+
+  test("a guard with no spec to read fails the job too", () => {
+    const r = spawnSync(process.execPath, ["-e", JOB_GUARD_JS], { env: { PATH: process.env.PATH ?? "" }, encoding: "utf-8" });
+    expect(r.status).toBe(CHANT_EXIT.misplaced);
+  });
+});

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

@@ -95,9 +95,9 @@ describe("a runner per wave and job groups per wave (#3914)", () => {
   test("tags, environment, id_tokens, variables and the group's command on each job", () => {
     const yaml = generateGitlabOpWavesPipeline(grouped, { specFile: "waves.json" }).files[0]!.yaml;
     expect(yaml).toMatch(/wave-1-dev:\n\s+stage: wave-1-dev\n\s+image: node:22\n\s+tags:\n\s+- docker\n\s+- dev\n/);
-    expect(yaml).toMatch(/wave-2-prod-decide:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- plan\n\s+resource_group: migrations-prod\n\s+id_tokens:\n\s+PLAN_TOKEN:\n\s+aud: plan.example\n/);
+    expect(yaml).toMatch(/wave-2-prod-decide:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- plan\n\s+timeout: '180 minutes'\n\s+id_tokens:\n\s+PLAN_TOKEN:\n\s+aud: plan.example\n/);
     expect(yaml).toMatch(
-      /wave-2-prod-us:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- us-apply\n\s+resource_group: migrations-prod\n\s+environment:\n\s+name: prod-us\n\s+id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: us.example\n\s+variables:\n\s+GIT_DEPTH: '0'\n\s+REGION: us\n[\s\S]*?needs:\n\s+- wave-2-prod-decide\n\s+script:\n\s+- echo us\n\s+- chant run wave --spec waves.json --wave 2 --group us\n/,
+      /wave-2-prod-us:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- us-apply\n\s+timeout: '180 minutes'\n\s+environment:\n\s+name: prod-us\n\s+id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: us.example\n\s+variables:\n\s+GIT_DEPTH: '0'\n\s+CHANT_LOCK_WAIT: '10500'\n\s+REGION: us\n\s+CHANT_JOB_GUARD: [^\n]*\n[\s\S]*?needs:\n\s+- wave-2-prod-decide\n\s+script:\n\s+- [^\n]*node -e[^\n]*\n\s+- echo us\n\s+- chant run wave --spec waves.json --wave 2 --group us\n/,
     );
     expect(yaml).toMatch(/wave-2-prod-eu:[\s\S]*?id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: eu.example\n/);
     expect(yaml).not.toContain("_AUDIENCE");
@@ -122,8 +122,10 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     for (const [name, ids] of Object.entries(want)) {
       const job = doc[name]!;
       expect(job.id_tokens).toEqual({ OTHER_TOKEN: { aud: "other.example" }, CHANT_ID_TOKEN_AWS: { aud: "sts.amazonaws.com" } });
-      expect(job.script.slice(0, 3)).toEqual(gitlabTradeLines());
-      expect(job.script[3]).toBe("npm ci");
+      // #4624: the apply-job guard first, then the trade.
+      expect(job.script[0]).toMatch(/^\(cd \/ && node -e '/);
+      expect(job.script.slice(1, 4)).toEqual(gitlabTradeLines());
+      expect(job.script[4]).toBe("npm ci");
       expect(tradeIdentities(JSON.parse(job.variables[TRADE_SPEC_ENV]!))).toEqual(ids);
     }
     expect(JSON.stringify(doc["wave-1-prod-decide"])).not.toContain("apply\"");
@@ -147,3 +149,12 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     expect(jobs.every((j) => j.command[0] === "chant")).toBe(true);
   });
 });
+
+describe("the ledger lock (ruling for ci-products 2026-10-28)", () => {
+  test("the wave jobs carry no resource_group; each carries its timeout and the lock wait under it", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json" }).files[0]!.yaml;
+    expect(yaml).not.toContain("resource_group");
+    expect(yaml).toContain("timeout: '180 minutes'\n");
+    expect(yaml).toContain("CHANT_LOCK_WAIT: '10500'\n");
+  });
+});

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

@@ -18,14 +18,23 @@
  * A wave's `environment` is the job's own `environment:`; protect it in the
  * project settings to put a reviewer in front of the job as well.
  *
+ * The wave jobs carry no `resource_group` (ruling for ci-products
+ * 2026-10-28, "Ledger lock"), the same as the GitHub and Forgejo waves files
+ * carry no concurrency group: a per-wave resource group would keep two
+ * pipelines' plunge stacks apart where their resource rows do not meet. A
+ * stock Pulumi stack or a Terraform root waits for its row on chant's ledger,
+ * oldest commit first, up to the job's `timeout`, which `CHANT_LOCK_WAIT`
+ * sits five minutes under; the project's own maximum timeout still caps it.
+ *
  * With `resume` on the spec (#3683), a `<name>-resume` job runs `chant run
  * resume --op <name>` in scheduled pipelines only: create a pipeline schedule
  * with the spec's cron. It retries a waiting wave's job once its approval
  * 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
@@ -49,6 +58,14 @@
  * 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 {
@@ -70,9 +87,13 @@ import {
 import {
   opWaveGroupOf,
   opWaveJobs,
+  opWaveJobTimeout,
   opWaveOutcomeDir,
   opWavesControlTarget,
   opWavesLastJobs,
+  OP_WAVES_APPROVAL_STATUS_VAR,
+  opWavesApprovalStatusCommand,
+  opWavesPostsApprovalStatus,
   opWavesOutcomeCommand,
   opWavesRecordPlansCommand,
   opWavesResumeCommand,
@@ -81,8 +102,14 @@ import {
 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, { bin: options.bin });
@@ -107,8 +134,10 @@ 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;
@@ -116,6 +145,8 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
   if (control) stages.push("control");
   if (spec.resume) stages.push("resume");
   const entries: Array<readonly [string, unknown]> = [["stages", stages]];
+  // The ruling for ci-products (2026-10-28): each wave job's timeout, and the lock wait five minutes under it.
+  const timeout = opWaveJobTimeout(options.jobTimeoutMinutes);
   const variables = nonEmpty("variables", options.variables).variables;
   if (variables) entries.push(["variables", variables]);
   if (byReview) {
@@ -130,6 +161,18 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
         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(" ")],
+      },
+    ]);
   }
   for (const job of jobs) {
     const wave = spec.waves[job.wave - 1]!;
@@ -141,21 +184,32 @@ 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,
       {
         stage: stages[job.wave - 1 + (byReview ? 1 : 0)],
         image,
         ...(tags ? { tags } : {}),
-        resource_group: `${spec.name}-${wave.name}`,
+        timeout: `${timeout.minutes} minutes`,
         ...(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, ...timeout.env, ...(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() : []), ...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] },
+        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" },
       },
     ]);
@@ -211,10 +265,15 @@ 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`;

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";
@@ -65,6 +67,10 @@ import {
   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";
@@ -441,9 +447,12 @@ function prLoopGitlabPipeline(
   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] : [])];
+  // #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, loop.words ? { ...(loop.words.bin ? { bin: loop.words.bin } : {}) } : undefined);
+  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> = {
@@ -468,8 +477,15 @@ function prLoopGitlabPipeline(
       stage: PR_PLAN_NOTE_JOB,
       image,
       rules: [{ if: onPlanNotes }],
+      ...(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,
@@ -567,6 +583,7 @@ function prLoopGitlabPipeline(
   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
       ? [
@@ -583,7 +600,16 @@ function prLoopGitlabPipeline(
     ...(controlJob ? [{ jobName: controlJob, component: "control repo dispatch", stage: control!.name, needs: [lastGreen!] }] : []),
     ...(prEnv ? prEnv.listed : []),
   ];
-  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));
+  // #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 };
 }
 

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");
+});

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

@@ -0,0 +1,27 @@
+/**
+ * The pull request loop's responses and description check on GitLab
+ * (#4629), as `chant build --pr-loop --respond --decide-backend
+ * --decide-model` sets them: `pr-post --open` asks the decide service, and
+ * the apply before merge carries CHANT_RESPOND and the merge (#4636).
+ */
+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" }] }] }];
+
+type Job = { variables?: Record<string, string>; script?: string[] };
+
+test("the note and apply jobs carry the responses, the decide service and the merge (#4629, #4636)", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, {
+    env: "prod",
+    prLoop: { applyBeforeMerge: true, applyMerge: { tokenEnv: "CHANT_MERGE_TOKEN" }, respond: { description: "check" }, decide: { backend: "review", model: "m-1" } },
+  }).yaml) as Record<string, Job>;
+  const note = doc["plan-note"]!;
+  expect(note.script!.at(-1)).toMatch(/pr-post --open .* --decide-backend "review" --decide-model "m-1"$/);
+  expect(note.variables!.CHANT_RESPOND).toBe("description=check");
+  const apply = Object.values(doc).find((j) => typeof j === "object" && j?.script?.some((l) => l.includes("--apply-before-merge")))!;
+  expect(apply.script!.join("\n")).toContain("--merge auto --merge-token-env CHANT_MERGE_TOKEN");
+  expect(apply.variables!.CHANT_RESPOND).toBe("description=check");
+});

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

@@ -0,0 +1,41 @@
+/**
+ * The merge request pipeline's runners, variables and passed secrets on
+ * GitLab (#4625): each job's `tags` from its stage's runner, and a passed
+ * secret mapped from the CI/CD variable when the names differ. Written for
+ * the ci-products post-merge pass.
+ */
+
+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" }] }] }];
+
+type Job = { tags?: string[]; variables: Record<string, string>; script: string[] };
+type Doc = Record<string, Job>;
+
+describe("the GitLab merge request pipeline's runners and variables (#4625)", () => {
+  const doc = parseYAML(
+    generateGitlabPipeline(ESTATE, {
+      env: "prod",
+      prLoop: { applyOnMerge: true, runners: { plan: "planner", apply: ["deploy", "eu"], default: "small" }, variables: { REGION: "eu" }, secrets: { DB_PASSWORD: "PROD_DB", SAME: "SAME" } },
+    }).yaml,
+  ) as Doc;
+
+  test("each job's tags come from its stage", () => {
+    expect(doc.plan!.tags).toEqual(["planner"]);
+    expect(doc.apply!.tags).toEqual(["deploy", "eu"]);
+    expect(doc.record!.tags).toEqual(["deploy", "eu"]);
+    expect(doc["plan-note"]!.tags).toEqual(["small"]);
+  });
+
+  test("the plan's variables carry the variable and the renamed secret; a same-named one needs no line", () => {
+    expect(doc.plan!.variables).toMatchObject({ REGION: "eu", DB_PASSWORD: "$PROD_DB" });
+    expect(doc.plan!.variables).not.toHaveProperty("SAME");
+  });
+
+  test("a runner group is refused", () => {
+    expect(() => generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { runners: { plan: { group: "g" } } } })).toThrow(/runner group/);
+  });
+});

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

@@ -0,0 +1,24 @@
+/**
+ * Stale marking on GitLab (#4628): the note job's `pr-post --open` passes
+ * the target branch pipeline's commit, and a stale-notes job in the push
+ * pipeline of the target branch runs `pr-post --stale`. 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" }] }] }];
+
+test("the note job carries the tip and a push job marks the notes stale (#4628)", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { staleNotes: true } }).yaml) as Record<string, unknown> & { stages: string[] };
+  const note = doc["plan-note"] as { variables: Record<string, string>; script: string[] };
+  expect(note.variables.TIP_SHA).toBe("$CI_COMMIT_SHA");
+  expect(note.script.at(-1)).toContain('--tip "$TIP_SHA"');
+  const stale = doc["stale-notes"] as { stage: string; rules: Array<{ if: string }>; variables: Record<string, string>; script: string[] };
+  expect(doc.stages).toContain("stale-notes");
+  expect(stale.rules[0]!.if).toContain("$CI_PIPELINE_SOURCE == \"push\"");
+  expect(stale.variables).toEqual({ TIP_SHA: "$CI_COMMIT_SHA" });
+  expect(stale.script.at(-1)).toBe('chant components pr-post --stale --tip "$TIP_SHA" --env prod --forge gitlab');
+});