@intentius/chant-lexicon-gitlab 0.124.40 → 0.124.42

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;AAgBjG,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;AAWH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAwBjG,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

@@ -35,8 +35,10 @@ import { assertGitlabBranch, CI_IMAGE, ciJobName, fillCommand, GITLAB_FULL_HISTO
 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, prLoopSetup, prLoopWaveJobs, prLoopWithWaves, } from "@intentius/chant/components/pr-pipeline";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, GITLAB_APPLY_PR_VAR, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, PR_ENV_REPORT_DIR, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
+import { FORGE_TOKEN_VARS, GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
 import { emitGitlabFile } from "./ci-jobs.js";
 /**
  * Synthesize a `.gitlab-ci.yml` pipeline from a set of components: one stage
@@ -214,6 +216,8 @@ function gatedWaveGitlabPipeline(components, env, image, beforeScript, extraScri
             variables: { ...GITLAB_FULL_HISTORY },
             script: [...prLoopSetup(image), ...beforeScript, job.command.join(" "), ...extraScript],
             ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+            // #4291: a wave runs after one that failed, and blocks only what depends on the failure.
+            ...(job.needs.length > 0 ? { when: "always" } : {}),
             artifacts: { when: "always", paths: [GATED_WAVE_RECORD] },
         };
     }
@@ -255,9 +259,37 @@ function gatedWaveGitlabPipeline(components, env, image, beforeScript, extraScri
  * before. They share the commit's cache key, so wave k pulls the record wave
  * k-1 pushed, and a retry of a wave that stopped at its gate pulls the one it
  * pushed itself.
+ *
+ * The plan job holds no forge token while the merge request's code runs
+ * (#4295, `@intentius/chant/ci-handover`): its script starts by unsetting
+ * the token variables, and `pr-plan --no-status` writes the note and the
+ * status into its report. The `plan-note` job after it, which GitLab hands
+ * the report artifact, checks out the target branch's commit and posts them
+ * with `chant components pr-post`. A CI/CD variable reaches every job of a
+ * merge request pipeline, so `unset` keeps it from the plan's code, and
+ * `CHANT_FORGE_TOKEN` as a protected variable keeps it from the pipeline
+ * altogether.
+ *
+ * With `identity` (#4296, `@intentius/chant/ci-identity`) the plan, record
+ * and apply jobs take an `id_tokens:` entry per cloud, and each script
+ * starts by trading it for the job's cloud identity: the plan and record
+ * jobs for the plan identity, the apply jobs for the apply identity. The
+ * plan job trades before any of the merge request's code runs, then unsets
+ * the token variables with the forge tokens and sources the credentials.
  */
 /** The dotenv report a gated apply wave hands the green commit it applies through (#4221). */
 const WAVE_GREEN_DOTENV = "chant-green.env";
+/**
+ * The rule of the apply before merge (#4301, ws-106): a pipeline of `branch`
+ * that a person started from the UI, the API or a trigger with
+ * `CHANT_APPLY_PR` set to the merge request's iid. GitLab builds a merge
+ * request's own pipeline from its own files, so the apply runs in one of the
+ * target branch's. The variable only names the merge request; `pr-apply
+ * --before-merge` reads the rest from GitLab.
+ */
+function gitlabApplyPrRule(branch) {
+    return `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $${GITLAB_APPLY_PR_VAR} =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == ${branch}`;
+}
 /** The rule of a pipeline for a pushed `ci/green/` tag (#4168 step 9), which runs the apply under apply on merge. */
 const GITLAB_GREEN_TAG_RULE = '$CI_COMMIT_TAG =~ /^ci\\/green\\//';
 function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript, options) {
@@ -272,7 +304,7 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
     // #4168 step 9: a push to the branch records, and under apply on merge a ci/green/ tag pipeline applies.
     const greens = loop.waveGate
         ? waveJobs.map((job) => ({ job, name: named(prApplyWaveJobName(job.wave)), stage: prApplyWaveJobName(job.wave) }))
-        : loop.applyOnMerge
+        : loop.applyOnMerge || loop.applyBeforeMerge
             ? [{ job: apply, name: named("apply"), stage: "apply" }]
             : [];
     const applies = [{ job: record, name: named("record"), stage: "record" }, ...greens];
@@ -280,28 +312,50 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
     if (loop.branch !== undefined)
         assertGitlabBranch("The merge-request pipeline", loop.branch);
     const onMerge = gitlabPushRule(loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH");
-    const onGreen = GITLAB_GREEN_TAG_RULE;
+    // #4301: the apply before merge runs in a pipeline of the target branch a person starts with CHANT_APPLY_PR set.
+    const onGreen = loop.applyBeforeMerge ? gitlabApplyPrRule(loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH") : GITLAB_GREEN_TAG_RULE;
     // A member's jobs start in its directory, after the image's install lines.
     const enter = rooted ? [] : [`cd ${memberShellDir(member)}`];
     // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY variable is set.
     // #4221: a wave job hands the commit it applies to the next wave as GREEN_SHA, through a dotenv report.
     const handOff = (job) => (job.wave ? [`echo "GREEN_SHA=$GREEN_SHA" > "$CI_PROJECT_DIR/${WAVE_GREEN_DOTENV}"`] : []);
     const script = (job) => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.checkout ?? []), ...handOff(job), ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
-    const stages = ["plan", ...applies.map((a) => a.stage)];
+    // #4296: each job trades its OIDC token for its cloud identity before anything else in its script.
+    const identity = loop.identity;
+    const trading = (spec) => spec ? { id_tokens: gitlabTradeIdTokens(spec) } : {};
+    const tradeVars = (spec) => (spec ? { [TRADE_SPEC_ENV]: JSON.stringify(spec) } : {});
+    const applySpec = (job) => (identity ? (job.jobName === "record" ? identity.plan : identity.apply) : undefined);
+    // #4298: a pull request environment's jobs, in a stage of their own after the plan.
+    const prEnv = loop.prEnvironment ? prEnvGitlabJobs(image, beforeScript, extraScript, enter, loop, member, named, onMergeRequest) : undefined;
+    const stages = ["plan", PR_PLAN_NOTE_JOB, ...applies.map((a) => a.stage), ...(prEnv ? [PR_ENV_STAGE, PR_ENV_POST_STAGE] : [])];
+    const noteJob = named(PR_PLAN_NOTE_JOB);
+    const post = prLoopPostJob("gitlab", env, member?.name);
     const doc = {
         // Included files merge their top-level keys, so a member's file carries
         // the rules every member shares and no name: two names would collide.
-        workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, ...(greens.length > 0 ? [{ if: onGreen }] : [])] },
+        workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, ...(greens.length > 0 ? [{ if: onGreen }] : []), ...(prEnv ? [{ if: GITLAB_SCHEDULE_RULE }] : [])] },
         stages,
         variables: { ...options.variables, CHANT_ENV: env, ...GITLAB_FULL_HISTORY },
         [planJob]: {
             stage: "plan",
             image,
             rules: [{ if: onMergeRequest }],
-            variables: plan.run.env,
-            script: script(plan),
+            ...trading(identity?.plan),
+            variables: { ...plan.run.env, ...tradeVars(identity?.plan) },
+            // #4295: the merge request's code runs in this job, so the job's shell drops the forge tokens first.
+            // #4296: with identity, the trade runs before that, and the same unset drops the token variables too.
+            script: [...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]), ...script(plan)],
             artifacts: { when: "always", paths: [reportPath] },
         },
+        // #4295: a fresh job at the target branch's commit posts the note and the status from the plan's report.
+        [noteJob]: {
+            stage: PR_PLAN_NOTE_JOB,
+            image,
+            needs: [planJob],
+            rules: [{ if: onMergeRequest, when: "always" }],
+            variables: post.env,
+            script: ['git checkout --quiet --detach "$BASE_SHA"', ...enter, ...beforeScript, post.command],
+        },
         ...Object.fromEntries(applies.map(({ job, name, stage }, i) => [
             name,
             {
@@ -309,9 +363,11 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
                 image,
                 ...(i > 1 ? { needs: [applies[i - 1].name] } : {}),
                 resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : prApplyGroup(env, member?.name),
-                rules: [{ if: job.jobName === "record" ? onMerge : onGreen }],
-                variables: job.run.env,
-                script: script(job),
+                // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
+                rules: [{ if: job.jobName === "record" ? onMerge : onGreen, ...(job.wave && i > 1 ? { when: "always" } : {}) }],
+                ...trading(applySpec(job)),
+                variables: { ...job.run.env, ...tradeVars(applySpec(job)) },
+                script: [...(applySpec(job) ? gitlabTradeLines() : []), ...script(job)],
                 // The attempt record (#3543), kept under the pushed commit even when
                 // the job fails, so a retry finishes the apply under the same approval.
                 // The record job (#4168) applies nothing and keeps none.
@@ -327,19 +383,98 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
                 artifacts: { when: "always", paths: [reportPath], ...(job.wave ? { reports: { dotenv: WAVE_GREEN_DOTENV } } : {}) },
             },
         ])),
+        ...(prEnv ? prEnv.jobs : {}),
     };
     const jobs = [
         { jobName: planJob, component: "merge request plan", stage: "plan", needs: [] },
+        { jobName: noteJob, component: "merge request plan note", stage: PR_PLAN_NOTE_JOB, needs: [planJob] },
         ...applies.map(({ job, name, stage }, i) => ({
             jobName: name,
-            component: job.wave ? `green apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : "green apply",
+            component: job.wave ? `green apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : "green apply",
             stage,
             needs: i > 1 ? [applies[i - 1].name] : [],
         })),
+        ...(prEnv ? prEnv.listed : []),
     ];
-    const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, ...applies.map((a) => a.name)].map((key) => [key, doc[key]]));
+    const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...applies.map((a) => a.name), ...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). */
+const PR_ENV_STAGE = "env";
+/** The rule of a scheduled pipeline, which runs `env-sweep` (#4298). */
+const GITLAB_SCHEDULE_RULE = '$CI_PIPELINE_SOURCE == "schedule"';
+/**
+ * A pull request environment's jobs on GitLab (#4298). `env-up` runs in the
+ * merge request pipeline and runs the change's code, so its script drops the
+ * forge tokens first, as the plan job's does (#4295), and it keeps its report
+ * and record as the artifact. `env-post`, at the target branch's commit,
+ * keeps the record on chant/lifecycle and posts the note. `env-up` starts a
+ * GitLab environment `pr-<iid>` whose stop job is `env-down`, so the
+ * environment's Stop button tears it down. GitLab starts no pipeline when a
+ * merge request closes, so `env-sweep`, from a pipeline schedule, is what
+ * tears down a closed merge request's environment unattended, as it does one
+ * whose TTL passed.
+ */
+function prEnvGitlabJobs(image, beforeScript, extraScript, enter, loop, member, named, onMergeRequest) {
+    const [up, post, down, sweep] = prEnvJobs("gitlab", loop, member?.name);
+    const reportPath = member ? memberRepoPath(member, PR_ENV_REPORT_DIR) : PR_ENV_REPORT_DIR;
+    const environment = "pr-$CI_MERGE_REQUEST_IID";
+    const group = `chant-pr-env-${member ? `${member.name}-` : ""}$CI_MERGE_REQUEST_IID`;
+    const script = (j) => [...prLoopSetup(image), ...enter, ...beforeScript, ...(j.build ?? []), j.command, ...extraScript];
+    const artifacts = { when: "always", paths: [reportPath] };
+    return {
+        jobs: {
+            [named("env-up")]: {
+                stage: PR_ENV_STAGE,
+                image,
+                rules: [{ if: onMergeRequest }],
+                resource_group: group,
+                environment: { name: environment, on_stop: named("env-down") },
+                variables: up.env,
+                // #4295: the merge request's code runs in this job, so the job's shell drops the forge tokens first.
+                script: [GITLAB_DROP_FORGE_TOKENS, ...script(up)],
+                artifacts,
+            },
+            [named(PR_ENV_POST_JOB)]: {
+                stage: PR_ENV_POST_STAGE,
+                image,
+                needs: [named("env-up")],
+                rules: [{ if: onMergeRequest, when: "always" }],
+                variables: post.env,
+                script: ['git checkout --quiet --detach "$BASE_SHA"', ...enter, ...beforeScript, post.command],
+                artifacts,
+            },
+            [named("env-down")]: {
+                stage: PR_ENV_STAGE,
+                image,
+                rules: [{ if: onMergeRequest, when: "manual" }],
+                allow_failure: true,
+                resource_group: group,
+                environment: { name: environment, action: "stop" },
+                variables: down.env,
+                script: script(down),
+                artifacts,
+            },
+            [named("env-sweep")]: {
+                stage: PR_ENV_STAGE,
+                image,
+                rules: [{ if: GITLAB_SCHEDULE_RULE }],
+                resource_group: `chant-pr-env-sweep${member ? `-${member.name}` : ""}`,
+                variables: sweep.env,
+                script: script(sweep),
+                artifacts,
+            },
+        },
+        listed: [
+            { jobName: named("env-up"), component: "merge request environment", stage: PR_ENV_STAGE, needs: [] },
+            { jobName: named(PR_ENV_POST_JOB), component: "merge request environment note", stage: PR_ENV_POST_STAGE, needs: [named("env-up")] },
+            { jobName: named("env-down"), component: "merge request environment teardown", stage: PR_ENV_STAGE, needs: [] },
+            { jobName: named("env-sweep"), component: "merge request environment sweep", stage: PR_ENV_STAGE, needs: [] },
+        ],
+    };
+}
+/** The stage the post job runs in, after `env-up` (#4295). */
+const PR_ENV_POST_STAGE = "env-post";
 /**
  * Scope a pipeline to one workspace member (#2542, #2524 D19), in place on
  * `doc` and `jobs`. Returns the promote job's new name.

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "524274c7aeb4edfd8d865037c7706c1fefaf33027d00fd2ce7afa4c809633a5d",
+    "manifest.json": "5eadeadbe17078f803f0afde8b3d6153f381305adae156307271887f23355170",
     "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": "56212233f186cc26ade3222cb96cfe5719dea084a89f4de37493fa9f292cf965"
+  "composite": "fcd516d1ec373a23058e366255e162fc527da7d2e62ce01a399255a37d893c91"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.124.40",
+  "version": "0.124.42",
   "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.40",
-    "@intentius/chant-lexicon-github": "^0.124.40"
+    "@intentius/chant": "^0.124.42",
+    "@intentius/chant-lexicon-github": "^0.124.42"
   },
   "peerDependenciesMeta": {
     "@intentius/chant-lexicon-github": {

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

@@ -7,6 +7,7 @@ workflow:
 
 stages:
   - plan
+  - plan-note
   - record
   - apply
 
@@ -23,6 +24,7 @@ plan:
     BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
     PR_NUMBER: '$CI_MERGE_REQUEST_IID'
   script:
+    - unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
     - command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
     - chant build --env prod
     - chant lint
@@ -32,6 +34,22 @@ plan:
     paths:
       - .chant/pr
 
+plan-note:
+  stage: plan-note
+  image: node:22
+  needs:
+    - plan
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+  variables:
+    PR_NUMBER: '$CI_MERGE_REQUEST_IID'
+    HEAD_SHA: '$CI_COMMIT_SHA'
+    BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
+  script:
+    - git checkout --quiet --detach "$BASE_SHA"
+    - chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge gitlab
+
 record:
   stage: record
   image: node:22

package/src/components/__fixtures__/pr-loop-record.gitlab.golden.yml

@@ -6,6 +6,7 @@ workflow:
 
 stages:
   - plan
+  - plan-note
   - record
 
 variables:
@@ -21,6 +22,7 @@ plan:
     BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
     PR_NUMBER: '$CI_MERGE_REQUEST_IID'
   script:
+    - unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
     - command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
     - chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge gitlab
   artifacts:
@@ -28,6 +30,22 @@ plan:
     paths:
       - .chant/pr
 
+plan-note:
+  stage: plan-note
+  image: node:22
+  needs:
+    - plan
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+  variables:
+    PR_NUMBER: '$CI_MERGE_REQUEST_IID'
+    HEAD_SHA: '$CI_COMMIT_SHA'
+    BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
+  script:
+    - git checkout --quiet --detach "$BASE_SHA"
+    - chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge gitlab
+
 record:
   stage: record
   image: node:22

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

@@ -7,6 +7,7 @@ workflow:
 
 stages:
   - plan
+  - plan-note
   - record
   - apply-wave-1
   - apply-wave-2
@@ -25,6 +26,7 @@ plan:
     BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
     PR_NUMBER: '$CI_MERGE_REQUEST_IID'
   script:
+    - unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
     - command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
     - chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge gitlab --wave-gate release
   artifacts:
@@ -32,6 +34,22 @@ plan:
     paths:
       - .chant/pr
 
+plan-note:
+  stage: plan-note
+  image: node:22
+  needs:
+    - plan
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+  variables:
+    PR_NUMBER: '$CI_MERGE_REQUEST_IID'
+    HEAD_SHA: '$CI_COMMIT_SHA'
+    BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
+  script:
+    - git checkout --quiet --detach "$BASE_SHA"
+    - chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge gitlab
+
 record:
   stage: record
   image: node:22
@@ -81,6 +99,7 @@ apply-wave-2:
   resource_group: chant-apply-prod
   rules:
     - if: '$CI_COMMIT_TAG =~ /^ci\/green\//'
+      when: always
   variables: {}
   script:
     - command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
@@ -107,6 +126,7 @@ apply-wave-3:
   resource_group: chant-apply-prod
   rules:
     - if: '$CI_COMMIT_TAG =~ /^ci\/green\//'
+      when: always
   variables: {}
   script:
     - command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)

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

@@ -7,6 +7,7 @@ workflow:
 
 stages:
   - plan
+  - plan-note
   - record
   - apply
 
@@ -23,6 +24,7 @@ plan:
     BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
     PR_NUMBER: '$CI_MERGE_REQUEST_IID'
   script:
+    - unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
     - command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
     - chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge gitlab
   artifacts:
@@ -30,6 +32,22 @@ plan:
     paths:
       - .chant/pr
 
+plan-note:
+  stage: plan-note
+  image: node:22
+  needs:
+    - plan
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+  variables:
+    PR_NUMBER: '$CI_MERGE_REQUEST_IID'
+    HEAD_SHA: '$CI_COMMIT_SHA'
+    BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
+  script:
+    - git checkout --quiet --detach "$BASE_SHA"
+    - chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge gitlab
+
 record:
   stage: record
   image: node:22

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

@@ -343,6 +343,9 @@ describe("generateGitlabPipeline: gated waves (#3049)", () => {
     expect(result.stages).toEqual(["wave-1", "wave-2", "wave-3"]);
     expect(parsed["wave-2"].needs).toEqual(["wave-1"]);
     expect(parsed["wave-1"].needs).toBeUndefined();
+    // #4291: wave 2 runs after wave 1 failed, so a failure blocks only its dependents.
+    expect(parsed["wave-2"].when).toBe("always");
+    expect(parsed["wave-1"].when).toBeUndefined();
     expect(parsed["wave-3"].image).toBe("node:22");
     expect(parsed["wave-3"].script).toEqual([
       expect.stringMatching(/^command -v tofu /),

package/src/components/generate-pipeline.ts

@@ -52,11 +52,19 @@ import {
   prApplyRecordKey,
   prApplyWaveJobName,
   prLoopJobs,
+  GITLAB_APPLY_PR_VAR,
+  prLoopPostJob,
   prLoopSetup,
+  PR_PLAN_NOTE_JOB,
   prLoopWaveJobs,
   prLoopWithWaves,
+  prEnvJobs,
+  PR_ENV_REPORT_DIR,
+  PR_ENV_POST_JOB,
 } from "@intentius/chant/components/pr-pipeline";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
+import { FORGE_TOKEN_VARS, GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV, type CloudTradeSpec } from "@intentius/chant/ci-identity";
 import type {
   ComponentPipelineJob as GeneratedJob,
   ComponentPipelineOptions as GenerateGitlabOptions,
@@ -258,6 +266,8 @@ function gatedWaveGitlabPipeline(
       variables: { ...GITLAB_FULL_HISTORY },
       script: [...prLoopSetup(image), ...beforeScript, job.command.join(" "), ...extraScript],
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+      // #4291: a wave runs after one that failed, and blocks only what depends on the failure.
+      ...(job.needs.length > 0 ? { when: "always" } : {}),
       artifacts: { when: "always", paths: [GATED_WAVE_RECORD] },
     };
   }
@@ -299,10 +309,39 @@ function gatedWaveGitlabPipeline(
  * before. They share the commit's cache key, so wave k pulls the record wave
  * k-1 pushed, and a retry of a wave that stopped at its gate pulls the one it
  * pushed itself.
+ *
+ * The plan job holds no forge token while the merge request's code runs
+ * (#4295, `@intentius/chant/ci-handover`): its script starts by unsetting
+ * the token variables, and `pr-plan --no-status` writes the note and the
+ * status into its report. The `plan-note` job after it, which GitLab hands
+ * the report artifact, checks out the target branch's commit and posts them
+ * with `chant components pr-post`. A CI/CD variable reaches every job of a
+ * merge request pipeline, so `unset` keeps it from the plan's code, and
+ * `CHANT_FORGE_TOKEN` as a protected variable keeps it from the pipeline
+ * altogether.
+ *
+ * With `identity` (#4296, `@intentius/chant/ci-identity`) the plan, record
+ * and apply jobs take an `id_tokens:` entry per cloud, and each script
+ * starts by trading it for the job's cloud identity: the plan and record
+ * jobs for the plan identity, the apply jobs for the apply identity. The
+ * plan job trades before any of the merge request's code runs, then unsets
+ * the token variables with the forge tokens and sources the credentials.
  */
 /** The dotenv report a gated apply wave hands the green commit it applies through (#4221). */
 const WAVE_GREEN_DOTENV = "chant-green.env";
 
+/**
+ * The rule of the apply before merge (#4301, ws-106): a pipeline of `branch`
+ * that a person started from the UI, the API or a trigger with
+ * `CHANT_APPLY_PR` set to the merge request's iid. GitLab builds a merge
+ * request's own pipeline from its own files, so the apply runs in one of the
+ * target branch's. The variable only names the merge request; `pr-apply
+ * --before-merge` reads the rest from GitLab.
+ */
+function gitlabApplyPrRule(branch: string): string {
+  return `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $${GITLAB_APPLY_PR_VAR} =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == ${branch}`;
+}
+
 /** The rule of a pipeline for a pushed `ci/green/` tag (#4168 step 9), which runs the apply under apply on merge. */
 const GITLAB_GREEN_TAG_RULE = '$CI_COMMIT_TAG =~ /^ci\\/green\\//';
 
@@ -325,35 +364,58 @@ function prLoopGitlabPipeline(
   // #4168 step 9: a push to the branch records, and under apply on merge a ci/green/ tag pipeline applies.
   const greens = loop.waveGate
     ? waveJobs.map((job) => ({ job, name: named(prApplyWaveJobName(job.wave!)), stage: prApplyWaveJobName(job.wave!) }))
-    : loop.applyOnMerge
+    : loop.applyOnMerge || loop.applyBeforeMerge
       ? [{ job: apply, name: named("apply"), stage: "apply" }]
       : [];
   const applies = [{ job: record, name: named("record"), stage: "record" }, ...greens];
   const onMergeRequest = GITLAB_MERGE_REQUEST_SOURCE;
   if (loop.branch !== undefined) assertGitlabBranch("The merge-request pipeline", loop.branch);
   const onMerge = gitlabPushRule(loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH");
-  const onGreen = GITLAB_GREEN_TAG_RULE;
+  // #4301: the apply before merge runs in a pipeline of the target branch a person starts with CHANT_APPLY_PR set.
+  const onGreen = loop.applyBeforeMerge ? gitlabApplyPrRule(loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH") : GITLAB_GREEN_TAG_RULE;
   // A member's jobs start in its directory, after the image's install lines.
   const enter = rooted ? [] : [`cd ${memberShellDir(member!)}`];
   // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY variable is set.
   // #4221: a wave job hands the commit it applies to the next wave as GREEN_SHA, through a dotenv report.
   const handOff = (job: typeof plan): string[] => (job.wave ? [`echo "GREEN_SHA=$GREEN_SHA" > "$CI_PROJECT_DIR/${WAVE_GREEN_DOTENV}"`] : []);
   const script = (job: typeof plan): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.checkout ?? []), ...handOff(job), ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
-  const stages = ["plan", ...applies.map((a) => a.stage)];
+  // #4296: each job trades its OIDC token for its cloud identity before anything else in its script.
+  const identity = loop.identity;
+  const trading = (spec: CloudTradeSpec | undefined): Record<string, unknown> =>
+    spec ? { id_tokens: gitlabTradeIdTokens(spec) } : {};
+  const tradeVars = (spec: CloudTradeSpec | undefined): Record<string, string> => (spec ? { [TRADE_SPEC_ENV]: JSON.stringify(spec) } : {});
+  const applySpec = (job: typeof plan): CloudTradeSpec | undefined => (identity ? (job.jobName === "record" ? identity.plan : identity.apply) : undefined);
+  // #4298: a pull request environment's jobs, in a stage of their own after the plan.
+  const prEnv = loop.prEnvironment ? prEnvGitlabJobs(image, beforeScript, extraScript, enter, loop, member, named, onMergeRequest) : undefined;
+  const stages = ["plan", PR_PLAN_NOTE_JOB, ...applies.map((a) => a.stage), ...(prEnv ? [PR_ENV_STAGE, PR_ENV_POST_STAGE] : [])];
+  const noteJob = named(PR_PLAN_NOTE_JOB);
+  const post = prLoopPostJob("gitlab", env, member?.name);
   const doc: Record<string, unknown> = {
     // Included files merge their top-level keys, so a member's file carries
     // the rules every member shares and no name: two names would collide.
-    workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, ...(greens.length > 0 ? [{ if: onGreen }] : [])] },
+    workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, ...(greens.length > 0 ? [{ if: onGreen }] : []), ...(prEnv ? [{ if: GITLAB_SCHEDULE_RULE }] : [])] },
     stages,
     variables: { ...options.variables, CHANT_ENV: env, ...GITLAB_FULL_HISTORY },
     [planJob]: {
       stage: "plan",
       image,
       rules: [{ if: onMergeRequest }],
-      variables: plan.run.env,
-      script: script(plan),
+      ...trading(identity?.plan),
+      variables: { ...plan.run.env, ...tradeVars(identity?.plan) },
+      // #4295: the merge request's code runs in this job, so the job's shell drops the forge tokens first.
+      // #4296: with identity, the trade runs before that, and the same unset drops the token variables too.
+      script: [...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]), ...script(plan)],
       artifacts: { when: "always", paths: [reportPath] },
     },
+    // #4295: a fresh job at the target branch's commit posts the note and the status from the plan's report.
+    [noteJob]: {
+      stage: PR_PLAN_NOTE_JOB,
+      image,
+      needs: [planJob],
+      rules: [{ if: onMergeRequest, when: "always" }],
+      variables: post.env,
+      script: ['git checkout --quiet --detach "$BASE_SHA"', ...enter, ...beforeScript, post.command],
+    },
     ...Object.fromEntries(
       applies.map(({ job, name, stage }, i) => [
         name,
@@ -362,9 +424,11 @@ function prLoopGitlabPipeline(
           image,
           ...(i > 1 ? { needs: [applies[i - 1]!.name] } : {}),
           resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : prApplyGroup(env, member?.name),
-          rules: [{ if: job.jobName === "record" ? onMerge : onGreen }],
-          variables: job.run.env,
-          script: script(job),
+          // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
+          rules: [{ if: job.jobName === "record" ? onMerge : onGreen, ...(job.wave && i > 1 ? { when: "always" } : {}) }],
+          ...trading(applySpec(job)),
+          variables: { ...job.run.env, ...tradeVars(applySpec(job)) },
+          script: [...(applySpec(job) ? gitlabTradeLines() : []), ...script(job)],
           // The attempt record (#3543), kept under the pushed commit even when
           // the job fails, so a retry finishes the apply under the same approval.
           // The record job (#4168) applies nothing and keeps none.
@@ -381,20 +445,112 @@ function prLoopGitlabPipeline(
         },
       ]),
     ),
+  ...(prEnv ? prEnv.jobs : {}),
   };
   const jobs: GeneratedJob[] = [
     { jobName: planJob, component: "merge request plan", stage: "plan", needs: [] },
+    { jobName: noteJob, component: "merge request plan note", stage: PR_PLAN_NOTE_JOB, needs: [planJob] },
     ...applies.map(({ job, name, stage }, i) => ({
       jobName: name,
-      component: job.wave ? `green apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : "green apply",
+      component: job.wave ? `green apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : "green apply",
       stage,
       needs: i > 1 ? [applies[i - 1]!.name] : [],
     })),
+    ...(prEnv ? prEnv.listed : []),
   ];
-  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, ...applies.map((a) => a.name)].map((key) => [key, doc[key]] as const));
+  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...applies.map((a) => a.name), ...Object.keys(prEnv?.jobs ?? {})].map((key) => [key, doc[key]] as const));
   return { yaml, stages, jobs, env };
 }
 
+/** The stage a pull request environment's jobs run in (#4298). */
+const PR_ENV_STAGE = "env";
+
+/** The rule of a scheduled pipeline, which runs `env-sweep` (#4298). */
+const GITLAB_SCHEDULE_RULE = '$CI_PIPELINE_SOURCE == "schedule"';
+
+/**
+ * A pull request environment's jobs on GitLab (#4298). `env-up` runs in the
+ * merge request pipeline and runs the change's code, so its script drops the
+ * forge tokens first, as the plan job's does (#4295), and it keeps its report
+ * and record as the artifact. `env-post`, at the target branch's commit,
+ * keeps the record on chant/lifecycle and posts the note. `env-up` starts a
+ * GitLab environment `pr-<iid>` whose stop job is `env-down`, so the
+ * environment's Stop button tears it down. GitLab starts no pipeline when a
+ * merge request closes, so `env-sweep`, from a pipeline schedule, is what
+ * tears down a closed merge request's environment unattended, as it does one
+ * whose TTL passed.
+ */
+function prEnvGitlabJobs(
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  enter: string[],
+  loop: NonNullable<GenerateGitlabOptions["prLoop"]>,
+  member: GenerateGitlabOptions["member"],
+  named: (job: string) => string,
+  onMergeRequest: string,
+): { jobs: Record<string, unknown>; listed: GeneratedJob[] } {
+  const [up, post, down, sweep] = prEnvJobs("gitlab", loop, member?.name);
+  const reportPath = member ? memberRepoPath(member, PR_ENV_REPORT_DIR) : PR_ENV_REPORT_DIR;
+  const environment = "pr-$CI_MERGE_REQUEST_IID";
+  const group = `chant-pr-env-${member ? `${member.name}-` : ""}$CI_MERGE_REQUEST_IID`;
+  const script = (j: typeof up): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(j.build ?? []), j.command, ...extraScript];
+  const artifacts = { when: "always", paths: [reportPath] };
+  return {
+    jobs: {
+      [named("env-up")]: {
+        stage: PR_ENV_STAGE,
+        image,
+        rules: [{ if: onMergeRequest }],
+        resource_group: group,
+        environment: { name: environment, on_stop: named("env-down") },
+        variables: up.env,
+        // #4295: the merge request's code runs in this job, so the job's shell drops the forge tokens first.
+        script: [GITLAB_DROP_FORGE_TOKENS, ...script(up)],
+        artifacts,
+      },
+      [named(PR_ENV_POST_JOB)]: {
+        stage: PR_ENV_POST_STAGE,
+        image,
+        needs: [named("env-up")],
+        rules: [{ if: onMergeRequest, when: "always" }],
+        variables: post.env,
+        script: ['git checkout --quiet --detach "$BASE_SHA"', ...enter, ...beforeScript, post.command],
+        artifacts,
+      },
+      [named("env-down")]: {
+        stage: PR_ENV_STAGE,
+        image,
+        rules: [{ if: onMergeRequest, when: "manual" }],
+        allow_failure: true,
+        resource_group: group,
+        environment: { name: environment, action: "stop" },
+        variables: down.env,
+        script: script(down),
+        artifacts,
+      },
+      [named("env-sweep")]: {
+        stage: PR_ENV_STAGE,
+        image,
+        rules: [{ if: GITLAB_SCHEDULE_RULE }],
+        resource_group: `chant-pr-env-sweep${member ? `-${member.name}` : ""}`,
+        variables: sweep.env,
+        script: script(sweep),
+        artifacts,
+      },
+    },
+    listed: [
+      { jobName: named("env-up"), component: "merge request environment", stage: PR_ENV_STAGE, needs: [] },
+      { jobName: named(PR_ENV_POST_JOB), component: "merge request environment note", stage: PR_ENV_POST_STAGE, needs: [named("env-up")] },
+      { jobName: named("env-down"), component: "merge request environment teardown", stage: PR_ENV_STAGE, needs: [] },
+      { jobName: named("env-sweep"), component: "merge request environment sweep", stage: PR_ENV_STAGE, needs: [] },
+    ],
+  };
+}
+
+/** The stage the post job runs in, after `env-up` (#4295). */
+const PR_ENV_POST_STAGE = "env-post";
+
 /**
  * Scope a pipeline to one workspace member (#2542, #2524 D19), in place on
  * `doc` and `jobs`. Returns the promote job's new name.

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

@@ -0,0 +1,91 @@
+/**
+ * A merge request's environment in the generated GitLab pipeline (#4298):
+ * `env-up` starts the GitLab environment `pr-<iid>` and drops the forge
+ * tokens before the merge request's code runs (#4295), `env-post` keeps the
+ * record and posts the note from the target branch's commit, `env-down` is
+ * the environment's stop job, and `env-sweep` runs from a pipeline schedule,
+ * since GitLab starts no pipeline when a merge request closes.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "kubectl-apply", manifest: "app.yaml" } as never] }] }];
+const SCHEMA = join(import.meta.dirname, "..", "codegen", "vendored", "gitlab-ci-schema.json");
+
+interface Job {
+  stage: string;
+  needs?: string[];
+  rules: Array<{ if: string; when?: string }>;
+  variables: Record<string, string>;
+  script: string[];
+  environment?: Record<string, string>;
+  resource_group?: string;
+}
+
+describe("the GitLab merge-request pipeline with a merge request environment", () => {
+  const result = generateGitlabPipeline(ESTATE, { env: "staging", image: "node:22", beforeScript: ["npm ci"], prLoop: { prEnvironment: true, build: true } });
+  const doc = parseYAML(result.yaml) as { workflow: { rules: Array<{ if: string }> }; stages: string[] } & Record<string, Job>;
+
+  test("validates against the vendored GitLab CI schema", () => {
+    const req = createRequire(import.meta.url);
+    const mod = req("ajv") as { default?: unknown };
+    const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): ((d: unknown) => boolean) & { errors?: unknown } };
+    const validate = new Ajv({ strict: false, allErrors: true }).compile(JSON.parse(readFileSync(SCHEMA, "utf-8")));
+    expect(validate(doc), JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  test("env-up starts pr-<iid> with env-down as its stop job, one run at a time per merge request", () => {
+    const up = doc["env-up"]!;
+    expect(doc.stages).toEqual(expect.arrayContaining(["env", "env-post"]));
+    expect(up.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]);
+    expect(up.environment).toEqual({ name: "pr-$CI_MERGE_REQUEST_IID", on_stop: "env-down" });
+    expect(up.variables).toEqual({ BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", CHANT_ENV: "pr-$CI_MERGE_REQUEST_IID" });
+    expect(up.script.at(-1)).toBe('chant components pr-env up --base "$BASE_SHA" --pr "$PR_NUMBER" --output .chant/pr-env --no-push');
+    const down = doc["env-down"]!;
+    expect(down.environment).toEqual({ name: "pr-$CI_MERGE_REQUEST_IID", action: "stop" });
+    expect(down.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"', when: "manual" }]);
+    expect(down.resource_group).toBe(up.resource_group);
+  });
+
+  test("env-sweep runs from a pipeline schedule, which the workflow rules let start", () => {
+    expect(doc["env-sweep"]!.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "schedule"' }]);
+    expect(doc.workflow.rules).toContainEqual({ if: '$CI_PIPELINE_SOURCE == "schedule"' });
+    expect(doc["env-sweep"]!.script.at(-1)).toBe("chant components pr-env sweep --forge gitlab --output .chant/pr-env");
+  });
+});
+
+describe("the GitLab env-up job holds no forge token while the merge request's code runs (#4295)", () => {
+  const result = generateGitlabPipeline(ESTATE, { env: "staging", image: "example/ci:1", beforeScript: ["npm ci"], prLoop: { prEnvironment: true, build: true } });
+  const doc = parseYAML(result.yaml) as Record<string, Job>;
+
+  test("env-up's script drops the tokens first, and every later line runs without them", () => {
+    const up = doc["env-up"]!;
+    expect(up.script[0]).toBe(GITLAB_DROP_FORGE_TOKENS);
+    const SECRET = "glpat-env-handover-4298";
+    const tokens = { GITLAB_TOKEN: SECRET, CHANT_FORGE_TOKEN: SECRET, CHANT_GITLAB_TOKEN: SECRET, CI_JOB_TOKEN: SECRET };
+    const lines = up.script.map((line, i) => (i === 0 ? line : `env | grep -c ${SECRET} || true`));
+    const out = execFileSync("sh", ["-c", lines.join("\n")], { env: { PATH: process.env.PATH ?? "/usr/bin:/bin", ...tokens }, encoding: "utf-8" });
+    expect(out.trim().split("\n").every((n) => n === "0")).toBe(true);
+    expect(up.variables).not.toHaveProperty("GITLAB_TOKEN");
+    expect(up.script.join("\n")).not.toContain("--forge");
+  });
+
+  test("env-post takes env-up's artifact, checks out the target branch's commit, and keeps the record and posts", () => {
+    const post = doc["env-post"]!;
+    expect(post.stage).toBe("env-post");
+    expect(post.needs).toEqual(["env-up"]);
+    expect(post.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"', when: "always" }]);
+    expect(post.variables).toEqual({ PR_NUMBER: "$CI_MERGE_REQUEST_IID", HEAD_SHA: "$CI_COMMIT_SHA", BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA" });
+    expect(post.script[0]).toBe('git checkout --quiet --detach "$BASE_SHA"');
+    expect(post.script.at(-1)).toBe('chant components pr-env post --pr "$PR_NUMBER" --head "$HEAD_SHA" --forge gitlab --output .chant/pr-env');
+    expect(post.script.join("\n")).not.toMatch(/chant (build|lint)|pr-env up/);
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * The merge-request pipeline with an apply before merge (#4301, ws-106).
+ * GitLab builds a merge request's own pipeline from its own files, so the
+ * apply runs in a pipeline of the target branch a person starts with
+ * CHANT_APPLY_PR set, and checks out the merge request's head there.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { pullRequestCheckout } from "@intentius/chant/components/pr-pipeline";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+interface Job { rules: Array<{ if: string }>; variables: Record<string, string>; script: string[]; resource_group?: string }
+
+describe("the GitLab pipeline with --apply-before-merge", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyBeforeMerge: true } }).yaml) as { workflow: { rules: Array<{ if: string }> }; record: Job; apply: Job };
+  const RULE = '$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $CHANT_APPLY_PR =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH';
+
+  test("the apply runs in a target-branch pipeline started with CHANT_APPLY_PR, and a push still records", () => {
+    expect(doc.apply.rules).toEqual([{ if: RULE }]);
+    expect(doc.workflow.rules.map((r) => r.if)).toContain(RULE);
+    expect(doc.record.rules[0]!.if).toContain('$CI_PIPELINE_SOURCE == "push"');
+    expect(doc.apply.resource_group).toBe("chant-apply-prod");
+  });
+
+  test("it checks out the merge request's head and applies before merge from the pipeline's commit", () => {
+    expect(doc.apply.variables).toMatchObject({ BASE_SHA: "$CI_COMMIT_SHA", PR_NUMBER: "$CHANT_APPLY_PR" });
+    const at = doc.apply.script.indexOf(pullRequestCheckout("gitlab"));
+    expect(at).toBeGreaterThanOrEqual(0);
+    expect(doc.apply.script.at(-1)).toBe('chant ci run apply --in-place --base "$BASE_SHA" --pr "$PR_NUMBER" --apply-before-merge --env prod --gate pr-apply --forge gitlab');
+  });
+});

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

@@ -0,0 +1,137 @@
+/**
+ * #4296: the merge-request pipeline's plan job trades its `id_tokens` for
+ * the plan identity before any of the merge request's code runs, then
+ * unsets the token variables, so that code never holds a token or the apply
+ * identity.
+ *
+ * The behaviour test runs the plan job's script in one shell, as GitLab
+ * does, with the job's id token variables and forge tokens set, against a
+ * local emulator of AWS STS (@intentius/chant/__fixtures__/oidc-emulator),
+ * and every line after the trade replaced by a probe. Test values only.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { FORGE_TOKEN_VARS, GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { gitlabTradeLines, idTokenVar, OIDC_REQUEST_VARS, resolveCloudIdentity, TRADE_SPEC_ENV, tradeIdentities, type PipelineCloudIdentity } from "@intentius/chant/ci-identity";
+import { emulatedCredentials, EMULATED_JWT_PREFIX, startOidcEmulator, type OidcEmulator } from "@intentius/chant/__fixtures__/oidc-emulator";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const run = promisify(execFile);
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+const PLAN_ROLE = "arn:aws:iam::111111111111:role/prod-plan";
+const APPLY_ROLE = "arn:aws:iam::111111111111:role/prod-apply";
+const IDENTITY = resolveCloudIdentity(
+  {
+    aws: { rules: [{ plan: PLAN_ROLE, apply: APPLY_ROLE }] },
+    azure: { tenantId: "test-tenant", rules: [{ plan: "plan-client", apply: "apply-client" }] },
+  },
+  "prod",
+)!;
+
+interface GitlabJob {
+  id_tokens?: Record<string, { aud: string }>;
+  variables?: Record<string, string>;
+  script: string[];
+}
+
+function pipeline(identity: PipelineCloudIdentity | undefined): Record<string, GitlabJob> {
+  const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", image: "example/ci:1", beforeScript: ["npm ci"], prLoop: { applyOnMerge: true, ...(identity ? { identity } : {}) } });
+  return parseYAML(yaml) as Record<string, GitlabJob>;
+}
+
+describe("the generated GitLab jobs' cloud identities (#4296)", () => {
+  const doc = pipeline(IDENTITY);
+  const plan = doc.plan!;
+
+  test("the plan job asks for one id token per cloud, and its script trades before anything else, then unsets the tokens", () => {
+    expect(plan.id_tokens).toEqual({ [idTokenVar("aws")]: { aud: "sts.amazonaws.com" }, [idTokenVar("azure")]: { aud: "api://AzureADTokenExchange" } });
+    expect(plan.script.slice(0, 3)).toEqual(gitlabTradeLines(FORGE_TOKEN_VARS));
+    expect(JSON.parse(plan.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.plan);
+  });
+
+  test("the plan job names no apply identity", () => {
+    const text = JSON.stringify(plan);
+    for (const id of tradeIdentities(IDENTITY.apply)) expect(text).not.toContain(id);
+  });
+
+  test("the record job takes the plan identity and the apply job the apply identity", () => {
+    expect(JSON.parse(doc.record!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.plan);
+    expect(JSON.parse(doc.apply!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.apply);
+    expect(doc.apply!.script.slice(0, 3)).toEqual(gitlabTradeLines());
+    expect(doc.apply!.id_tokens).toEqual(plan.id_tokens);
+  });
+
+  test("the plan-note job asks for no id token", () => {
+    expect(doc["plan-note"]!.id_tokens).toBeUndefined();
+  });
+
+  test("without identity the plan script starts as #4295 left it, and no job asks for an id token", () => {
+    const plain = pipeline(undefined);
+    expect(plain.plan!.script[0]).toBe(GITLAB_DROP_FORGE_TOKENS);
+    for (const [name, job] of Object.entries(plain)) if (typeof job === "object" && job && "script" in job) expect((job as GitlabJob).id_tokens, name).toBeUndefined();
+  });
+});
+
+const dirs: string[] = [];
+let emu: OidcEmulator;
+beforeAll(async () => {
+  emu = await startOidcEmulator();
+});
+afterAll(async () => {
+  await emu.close();
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const BASE = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp" };
+const FORGE_SECRET = "glpat_identity_secret_4296";
+
+describe("the generated plan script, run: the merge request's code never holds a token or the apply identity (#4296)", () => {
+  test("after the trade, the shell and its children see plan credentials and none of the id tokens", async () => {
+    const identity: PipelineCloudIdentity = { plan: emu.pointAt(IDENTITY.plan), apply: emu.pointAt(IDENTITY.apply) };
+    const plan = pipeline(identity).plan!;
+    const dir = mkdtempSync(join(tmpdir(), "chant-identity-gitlab-"));
+    dirs.push(dir);
+    const seen = join(dir, "seen");
+    const jwt = (cloud: string) => `${EMULATED_JWT_PREFIX}.${cloud}.gitlab`;
+    // GitLab runs the job's script lines in one shell, with the job's variables and id tokens set.
+    const script = [...plan.script.slice(0, 3), `env > "${seen}"`, `sh -c 'env' >> "${seen}"`].join("\n");
+    const file = join(dir, "job.sh");
+    writeFileSync(file, script);
+    const env = {
+      ...BASE,
+      ...Object.fromEntries(FORGE_TOKEN_VARS.map((v) => [v, `${FORGE_SECRET}_${v}`])),
+      ...plan.variables,
+      [idTokenVar("aws")]: jwt("aws"),
+      [idTokenVar("azure")]: jwt("azure"),
+      CI_JOB_ID: "4296",
+      TMPDIR: dir,
+    };
+    const before = emu.log.assumed.length;
+    const r = await run("sh", ["-e", file], { cwd: dir, env }).catch((e: { stderr: string }) => {
+      throw new Error(e.stderr);
+    });
+    expect(r.stderr).toContain(`traded the job's OIDC token for ${PLAN_ROLE}`);
+    expect(emu.log.assumed.slice(before)).toEqual([{ role: PLAN_ROLE, token: jwt("aws") }]);
+    expect(emu.log.clients.at(-1)).toEqual({ clientId: "plan-client", token: jwt("azure") });
+    const text = readFileSync(seen, "utf-8");
+    expect(text).toContain(`AWS_ACCESS_KEY_ID=${emulatedCredentials(PLAN_ROLE).accessKeyId}`);
+    expect(text).toContain("AZURE_CLIENT_ID=plan-client");
+    expect(text).not.toContain(EMULATED_JWT_PREFIX);
+    expect(text).not.toContain(FORGE_SECRET);
+    expect(text).not.toContain(APPLY_ROLE);
+    expect(text).not.toContain("apply-client");
+    for (const v of OIDC_REQUEST_VARS) expect(text).not.toMatch(new RegExp(`^${v}=`, "m"));
+    // The credentials file is gone once sourced.
+    expect(readFileSync(seen, "utf-8")).not.toContain("chant-cloud-4296.sh=");
+    expect(() => readFileSync(join(dir, "chant-cloud-4296.sh"))).toThrow();
+  });
+});

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

@@ -5,6 +5,7 @@
  * CI schema this lexicon vendors.
  */
 
+import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
@@ -13,6 +14,7 @@ import { parseYAML } from "@intentius/chant/yaml";
 import type { DriverComponent } from "@intentius/chant/components/driver";
 import { generateGitlabPipeline } from "./generate-pipeline";
 import { greenCheckout, PR_LOOP_SETUP, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
+import { GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
 
 const ESTATE: DriverComponent[] = [
   { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
@@ -54,7 +56,9 @@ describe("the GitLab merge-request pipeline", () => {
   test("plans in a merge request pipeline from its diff base, records on a push to the default branch, applies on a ci/green/ tag, one at a time", () => {
     expect(doc.plan.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]);
     expect(doc.plan.variables).toEqual({ BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" });
+    // #4295: the merge request's code runs here, so the script drops the forge tokens first.
     expect(doc.plan.script).toEqual([
+      GITLAB_DROP_FORGE_TOKENS,
       ...PR_LOOP_SETUP,'chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge gitlab']);
     expect(doc.record.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]);
     expect(doc.record.variables).toEqual({ BASE_SHA: "$CI_COMMIT_BEFORE_SHA" });
@@ -121,7 +125,7 @@ describe("the GitLab merge-request pipeline", () => {
     const member = { name: "network", dir: "infra/network", file: ".gitlab/ci/chant-pr.network.prod.gitlab-ci.yml" };
     const scoped = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, member });
     const mdoc = parseYAML(scoped.yaml) as Record<string, unknown> & { workflow: { name?: string; rules: unknown[] } };
-    expect(scoped.jobs.map((j) => j.jobName)).toEqual(["network-plan", "network-record", "network-apply"]);
+    expect(scoped.jobs.map((j) => j.jobName)).toEqual(["network-plan", "network-plan-note", "network-record", "network-apply"]);
     expect(mdoc.plan).toBeUndefined();
     // Included files merge top-level keys: no name, so members do not collide on it.
     expect(mdoc.workflow.name).toBeUndefined();
@@ -162,7 +166,7 @@ describe("the gitlab pull-request pipeline with build (#4088)", () => {
     const script = (job: string) => (doc[job] as { script: string[] }).script;
     for (const job of ["plan", "apply"]) {
       const lines = script(job);
-      const i = lines.findIndex((l) => l.startsWith("chant components pr-"));
+      const i = lines.findIndex((l) => l.startsWith(`chant ci run ${job}`));
       expect(lines.slice(i - 2, i)).toEqual(["chant build --env prod", "chant lint"]);
     }
   });
@@ -199,7 +203,7 @@ describe("the GitLab merge-request pipeline records on merge by default (#4168)"
   });
 
   test("a push to the default branch runs the record job, which applies nothing and keeps no cache", () => {
-    expect(doc.stages).toEqual(["plan", "record"]);
+    expect(doc.stages).toEqual(["plan", "plan-note", "record"]);
     expect(doc.apply).toBeUndefined();
     expect(doc.record.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]);
     expect(doc.record.script.at(-1)).toBe('chant ci run record --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge gitlab');
@@ -217,3 +221,34 @@ describe("the GitLab merge-request pipeline records on merge by default (#4168)"
     expect(scoped["network-record"].script.at(-1)).toContain("chant ci run record");
   });
 });
+
+describe("the GitLab plan job holds no forge token while the merge request's code runs (#4295)", () => {
+  const result = generateGitlabPipeline(ESTATE, { env: "prod", image: "example/ci:1", beforeScript: ["npm ci"], prLoop: { build: true } });
+  const doc = parseYAML(result.yaml) as Record<string, Job & { stage: string; rules: Array<{ if: string; when?: string }> }>;
+
+  test("the plan's script drops the tokens first, and every later line runs without them", () => {
+    const plan = doc.plan!;
+    expect(plan.script[0]).toBe(GITLAB_DROP_FORGE_TOKENS);
+    // GitLab runs the script in one shell: each line after the first, run there with the tokens set, sees none of them.
+    const SECRET = "glpat-handover-4295";
+    const tokens = { GITLAB_TOKEN: SECRET, CHANT_FORGE_TOKEN: SECRET, CHANT_GITLAB_TOKEN: SECRET, CI_JOB_TOKEN: SECRET };
+    const lines = plan.script.map((line, i) => (i === 0 ? line : `env | grep -c ${SECRET} || true`));
+    const out = execFileSync("sh", ["-c", lines.join("\n")], { env: { PATH: process.env.PATH ?? "/usr/bin:/bin", ...tokens }, encoding: "utf-8" });
+    expect(out.trim().split("\n").every((n) => n === "0")).toBe(true);
+    expect(plan.variables).not.toHaveProperty("GITLAB_TOKEN");
+    expect(prLoopJobs("gitlab", "prod")[0]!.command.endsWith(" --no-status")).toBe(true);
+  });
+
+  test("the plan-note job takes the plan's artifact, checks out the target branch's commit, and posts", () => {
+    const note = doc["plan-note"]!;
+    expect(note.stage).toBe("plan-note");
+    expect(note.needs).toEqual(["plan"]);
+    expect(note.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"', when: "always" }]);
+    expect(note.variables).toEqual({ PR_NUMBER: "$CI_MERGE_REQUEST_IID", HEAD_SHA: "$CI_COMMIT_SHA", BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA" });
+    expect(note.script[0]).toBe('git checkout --quiet --detach "$BASE_SHA"');
+    expect(note.script.at(-1)).toBe('chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge gitlab');
+    // It runs no build, lint or plan: none of the merge request's code.
+    expect(note.script.join("\n")).not.toMatch(/chant (build|lint|ci run)/);
+    expect(result.stages).toEqual(["plan", "plan-note", "record"]);
+  });
+});

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

@@ -62,9 +62,10 @@ describe("the GitLab merge-request pipeline with a gate per wave (#4003)", () =>
   });
 
   test("one apply job and stage per wave, each needing the one before, on the merge, one at a time", () => {
-    expect(doc.stages).toEqual(["plan", "record", "apply-wave-1", "apply-wave-2", "apply-wave-3"]);
+    expect(doc.stages).toEqual(["plan", "plan-note", "record", "apply-wave-1", "apply-wave-2", "apply-wave-3"]);
     expect(result.jobs.map((j) => [j.jobName, j.needs])).toEqual([
       ["plan", []],
+      ["plan-note", ["plan"]],
       ["record", []],
       ["apply-wave-1", []],
       ["apply-wave-2", ["apply-wave-1"]],
@@ -89,6 +90,7 @@ describe("the GitLab merge-request pipeline with a gate per wave (#4003)", () =>
     const scoped = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, gatedWaves: { gate: "release" }, member });
     expect(scoped.jobs.map((j) => [j.jobName, j.needs])).toEqual([
       ["network-plan", []],
+      ["network-plan-note", ["network-plan"]],
       ["network-record", []],
       ["network-apply-wave-1", []],
       ["network-apply-wave-2", ["network-apply-wave-1"]],