@intentius/chant-lexicon-gitlab 0.59.0 → 0.61.0

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

@@ -1,65 +1,102 @@
 /**
- * Generate mode — scheduled Op → GitLab CI YAML (#927).
+ * Generate mode — Op → GitLab CI YAML (#927, #2084, #2256).
  *
  * The Op counterpart to `./generate-pipeline.ts` (#563): that module
  * synthesizes a deploy-time component graph as one `.gitlab-ci.yml`; this one
- * synthesizes a cron-triggered job per stateless Op. An Op's cadence is an
- * `OpSchedule` on the Op itself (`packages/core/src/op/types.ts`),
- * runtime-neutral data each reader interprets; this module is the reader that
- * turns it into a GitLab pipeline schedule (`WorkflowAuditOp`/
- * `PipelineAuditOp`/`ReconcileOp` all accept an optional `schedule` precisely
- * for this).
+ * synthesizes one job per Op, selected by its own `rules:`.
+ *
+ * What GitLab genuinely lacks is in-file cron. A schedule is a project-level
+ * object (Settings → CI/CD → Schedules) that runs the project's *existing*
+ * `.gitlab-ci.yml` with a chosen cron and CI/CD variables, so a cron-triggered
+ * Op becomes a job gated on `$CI_PIPELINE_SOURCE == "schedule"` plus a per-Op
+ * selector variable, and the generated file's header says what to set up. What
+ * GitLab does not lack, and what this generator wrongly refused until #2256,
+ * is the other two triggers (#2084): `$CI_PIPELINE_SOURCE` distinguishes
+ * `merge_request_event` from `push` on every pipeline, and `rules:` selects a
+ * job on either. So:
+ *
+ *  - `cron` → `$CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP ==
+ *    "<name>"`, unchanged;
+ *  - `pull_request` → `$CI_PIPELINE_SOURCE == "merge_request_event"`, with the
+ *    branch filter mapped to `$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, which is
+ *    the branch the merge request would merge INTO — the same thing github's
+ *    `on.pull_request.branches` filters on;
+ *  - `push` → `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH ==
+ *    "<branch>"`, defaulting to the same `main` github's generator assumes.
+ *
+ * Two or more branches are two or more rule entries, because `rules:` is an
+ * OR over its entries and a regex alternation would need every branch name
+ * escaped into a pattern.
+ *
+ * Every job carries a `resource_group`, GitLab's stand-in for github's per-Op
+ * `concurrency` group: one run at a time per Op, the next one queued rather
+ * than cancelled. On an apply job that is also what stops two runs racing for
+ * the same state lock.
+ *
+ * Unlike github, all of this lands in ONE file. A GitHub trigger is
+ * workflow-scoped, so an Op there needs its own workflow; a GitLab trigger is
+ * job-scoped, so the whole set is one document with one job apiece.
  *
- * Unlike GitHub Actions' per-workflow `on.schedule`, GitLab has no in-file
- * cron at all — a schedule is a project-level object (Settings → CI/CD →
- * Schedules) that runs the project's *existing* `.gitlab-ci.yml` with a
- * chosen cron and CI/CD variables. So every scheduled Op here becomes one
- * job in a single generated file, gated to run only under its own Pipeline
- * Schedule (`$CI_PIPELINE_SOURCE == "schedule"` plus a per-op selector
- * variable) — the cron itself is configured on the Pipeline Schedule, not in
- * this YAML, and the generated file's header comment states what to set up.
  * Each job runs exactly one invocation, `chant run <name>` by default — never
- * inlined audit/reconcile logic. The finding-mode itself is already baked
- * into the Op's own activity args at build time by the composite that
- * created it; GitLab has no per-job `permissions:` concept (unlike GitHub
- * Actions), and `findingMode: "comment"` is refused by name here because it
- * posts onto a GitHub pull-request event GitLab does not have (#2231), so a
- * non-`report` mode's write access comes from whatever
- * `GITLAB_TOKEN`/CI-CD-variable configuration the project already has —
- * this generator documents the requirement rather than fabricating a
- * variable nothing reads.
+ * inlined audit/reconcile logic. The finding-mode is already baked into the
+ * Op's own activity args at build time by the composite that created it; this
+ * generator only wires what the mode needs to act.
+ *
+ * `findingMode: "comment"` works here since #2256: `reconcilePr` writes a
+ * merge-request note when the run is a `merge_request_event` pipeline, by the
+ * same hidden-marker edit-in-place recipe it uses on a GitHub pull request.
+ * What survives of the old blanket refusal is the constraint github already
+ * has — the mode posts onto the merge request that triggered the run, so a
+ * cron or push job carrying it is refused by name at build time rather than
+ * emitted to fail at its Report step ({@link assertTriggerSupportsMode}).
+ * GitLab has no per-job `permissions:` concept, so the note's write access
+ * comes from a `GITLAB_TOKEN` CI/CD variable, which the header names.
+ *
+ * #2242's two per-Op options cross over one and a half times. A `setup` entry
+ * spelled `{ uses }` is a GitHub Actions marketplace action; GitLab CI has
+ * `script` and nothing else, so there is no shape to translate it into and it
+ * is refused by name. A `{ run }` entry translates exactly, and is emitted
+ * ahead of the `beforeScript` lines — in `script:` rather than
+ * `before_script:`, which is where `./generate-pipeline.ts` puts the same
+ * option's lines in this same lexicon, and which concatenates identically at
+ * run time. An additive `permissions` map has exactly one entry with a GitLab
+ * meaning: `id-token: write` becomes an `id_tokens:` declaration ({@link
+ * idTokensFor}), the OIDC surface the old refusal already named as the shape
+ * to reach for. Every other scope is still refused, because there is no
+ * per-job token-scope mapping to put it in and a silently dropped scope emits
+ * a job that reads as granted and runs with nothing.
  *
- * Neither of #2242's two per-Op options survives the crossing, and both are
- * refused by name rather than dropped. A `setup` entry spelled `{ uses }` is
- * a GitHub Actions marketplace action; GitLab CI has `script` and nothing
- * else, so there is no shape to translate it into and no way to approximate
- * `aws-actions/configure-aws-credentials` in a shell line. A `{ run }` entry
- * translates exactly, and is emitted ahead of the `beforeScript` lines, the
- * same position the github generator gives it. An additive `permissions` map
- * is refused for the same reason `permissions:` is absent here at all: GitLab
- * has no per-job token-scope mapping, and its OIDC surface is a different
- * declaration (`id_tokens:` with an `aud`, exchanged for cloud credentials by
- * the job itself) that chant does not generate. Ignoring the map would emit a
- * job that reads as having OIDC and runs with no credentials.
+ * A spec's `environment` (#2257) does cross, because GitLab has the concept
+ * under the same key and with the same two fields: `environment: { name, url
+ * }` on the job, an environment object in the project, and — on a protected
+ * environment — an approval rule that holds the deployment job until an
+ * approver releases it. So the reviewer gate the option exists for is
+ * expressible here, unlike the `uses` setup step above, and it is emitted
+ * rather than refused. What GitLab does not have is any way for this file to
+ * declare the protection: an environment's approval rules are project
+ * settings (Settings > CI/CD > Protected environments), exactly as GitHub's
+ * required reviewers are repository settings, so the generated header names
+ * the environment to protect the way it already names the schedule to create.
+ * chant's own gate (#2119) runs inside the job either way.
  *
- * The gated-apply mapping (#2243) has nothing to attach to here. It exists
- * because a push-to-main apply that stops at its gate exits 3 and paints the
- * branch red on every merge; this generator has no push pipeline at all,
- * refusing a `push` trigger by name (#2084) because a GitLab schedule is a
- * project-level cron object rather than an event. GitLab does have its own
- * equivalent of the mapping should one ever be wanted — `allow_failure:
- * { exit_codes: [3] }` turns one exit code into a warning rather than a
- * failure, without a flag on the invocation — so the day this generator
- * grows a push trigger, that is the shape to reach for rather than
- * `--gated-exit`.
+ * The gated apply (#2243) lands in the two surfaces GitLab has. `chant run`
+ * returns 3 when a run stops at an unapproved gate, so a push-to-default apply
+ * would paint the branch red on every merge until someone approves; the push
+ * job runs with `--gated-exit 0`, mapping that one outcome and nothing else.
+ * Where GitHub Actions gets the pending block on its run page through
+ * `GITHUB_STEP_SUMMARY`, GitLab has no step summary at all, so the job sets
+ * `CHANT_GATE_SUMMARY` to a path it also declares under `artifacts:` and the
+ * block is downloadable from the pipeline. The human render is already in the
+ * job log, since the invocation carries no `--json`. There is no follow-up
+ * notice job: it would need a forge API call and a token this generator does
+ * not require of a `report`-mode Op.
  */
 import type { ComponentPipelineOptions as GenerateGitlabOpOptions, OpPipelineResult as GenerateGitlabOpResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
 export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
 /**
- * Synthesize one `.gitlab-ci.yml` job per scheduled Op, all in a single file
- * (GitLab has no per-file cron — see the module doc). Wired into core's Op
- * generate mode via the gitlab lexicon plugin's `generateOpPipeline`
- * (../plugin.ts).
+ * Synthesize one `.gitlab-ci.yml` job per Op, all in a single file (a GitLab
+ * trigger is job-scoped — see the module doc). Wired into core's Op generate
+ * mode via the gitlab lexicon plugin's `generateOpPipeline` (../plugin.ts).
  */
 export declare function generateGitlabOpPipeline(ops: ScheduledOpSpec[], options?: GenerateGitlabOpOptions): GenerateGitlabOpResult;
 //# sourceMappingURL=generate-op-pipeline.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAGnD,gBAAgB,IAAI,sBAAsB,EAC1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAiClC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAmBhE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAmExB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAkQhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CA0FxB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "05eca8e8e24c1045cd8d1b9903dfa59661449d40b52b9d2f880eb2a5a00c67d2",
+    "manifest.json": "c68e008d70828d518ed8908e47729c0783c3b473fe4997f54d67366ae58be0b5",
     "meta.json": "931fc3246a55645b1493080bbeb160e5d205e42349e8bdca96ca243adb5f0da3",
     "types/index.d.ts": "5cd2e99f135a929b72bdd822d00d780d39b1cd407ba0cfb3d511c7ac9d667b58",
     "rules/artifact-no-expiry.ts": "3f3cabf9792cbf8207e53a25f506715466b19ec25e9c3b4d0d77fed6b2eb4542",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "5ba4e358f25944a07f0966355b274aebb3c199d11fc997aa7713830c7ff5320e"
+  "composite": "40909e34fc71fe00e52febba2c3bd87e1287416e19c8ab58a5f769a24af7f34e"
 }

package/dist/manifest.json

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

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAoB7F,eAAO,MAAM,YAAY,EAAE,aAmhB1B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAoB7F,eAAO,MAAM,YAAY,EAAE,aAohB1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "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.59.0",
-    "@intentius/chant-lexicon-github": "^0.59.0",
+    "@intentius/chant": "^0.61.0",
+    "@intentius/chant-lexicon-github": "^0.61.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {

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

@@ -70,33 +70,190 @@ describe("generateGitlabOpPipeline: one file, one job per scheduled Op", () => {
   });
 });
 
-describe("generateGitlabOpPipeline: no pull_request/push event model (#2084)", () => {
-  test("a pull_request trigger throws a clear error instead of silently ignoring it", () => {
-    const specs: ScheduledOpSpec[] = [{ name: "tf-plan", trigger: { kind: "pull_request" } }];
-    expect(() => generateGitlabOpPipeline(specs)).toThrow(/pull_request.*GitLab has no pull_request\/push event model/s);
+/**
+ * #2084's trigger pair, now that GitLab has both events after all (#2256).
+ *
+ * The two refusals this replaces ("GitLab has no pull_request/push event
+ * model" on either trigger) were wrong about GitLab rather than about chant:
+ * `$CI_PIPELINE_SOURCE` distinguishes `merge_request_event` from `push` on
+ * every pipeline, and `rules:` selects a job on either. What is genuinely
+ * absent is in-file cron, which is why the cron path still runs off a
+ * project-level Pipeline Schedule and is unchanged below.
+ */
+describe("generateGitlabOpPipeline: the merge_request and push triggers (#2084, #2256)", () => {
+  test("a pull_request trigger becomes a merge_request_event rule filtered to the target branch", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "tf-plan", trigger: { kind: "pull_request", branches: ["main"] } },
+    ]);
+    const job = parseYAML(result.files[0].yaml)["tf-plan"] as Record<string, unknown>;
+    expect(job.rules).toEqual([
+      {
+        if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"',
+      },
+    ]);
+  });
+
+  test("an unfiltered pull_request trigger fires on every merge request", () => {
+    const result = generateGitlabOpPipeline([{ name: "tf-plan", trigger: { kind: "pull_request" } }]);
+    const job = parseYAML(result.files[0].yaml)["tf-plan"] as Record<string, unknown>;
+    expect(job.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]);
+  });
+
+  test("two target branches are two rules, which is how GitLab spells an OR", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "tf-plan", trigger: { kind: "pull_request", branches: ["main", "release"] } },
+    ]);
+    const job = parseYAML(result.files[0].yaml)["tf-plan"] as { rules: Array<{ if: string }> };
+    expect(job.rules.map((r) => r.if)).toEqual([
+      '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"',
+      '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "release"',
+    ]);
+  });
+
+  test("a push trigger becomes a push rule on the named branch", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "tf-apply", trigger: { kind: "push", branches: ["release"] } },
+    ]);
+    const job = parseYAML(result.files[0].yaml)["tf-apply"] as Record<string, unknown>;
+    expect(job.rules).toEqual([
+      { if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "release"' },
+    ]);
+  });
+
+  test("an unfiltered push trigger defaults to main, the same branch github's generator assumes", () => {
+    const result = generateGitlabOpPipeline([{ name: "tf-apply", trigger: { kind: "push" } }]);
+    const job = parseYAML(result.files[0].yaml)["tf-apply"] as { rules: Array<{ if: string }> };
+    expect(job.rules[0].if).toBe('$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"');
+  });
+
+  test("every job carries a resource_group, GitLab's own per-Op concurrency", () => {
+    // github's `concurrency: { group, cancel-in-progress: false }` queues a
+    // second run rather than cancelling the first, which is exactly what a
+    // resource_group does — and on an apply job it is also the thing that
+    // stops two runs racing for the same state lock.
+    const result = generateGitlabOpPipeline([
+      { name: "tf-plan", trigger: { kind: "pull_request" } },
+      { name: "tf-apply", trigger: { kind: "push" } },
+      { name: "nightly", schedule: "0 6 * * *" },
+    ]);
+    const parsed = parseYAML(result.files[0].yaml);
+    for (const name of ["tf-plan", "tf-apply", "nightly"]) {
+      expect((parsed[name] as Record<string, unknown>).resource_group).toBe(name);
+    }
   });
 
-  test("a push trigger throws a clear error instead of silently ignoring it", () => {
-    const specs: ScheduledOpSpec[] = [{ name: "tf-apply", trigger: { kind: "push" } }];
-    expect(() => generateGitlabOpPipeline(specs)).toThrow(/push.*GitLab has no pull_request\/push event model/s);
+  test("mixed triggers still land in one file, because a GitLab trigger is job-scoped", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "tf-plan", trigger: { kind: "pull_request", branches: ["main"] } },
+      { name: "tf-apply", trigger: { kind: "push", branches: ["main"] } },
+      { name: "nightly", schedule: "0 6 * * *" },
+    ]);
+    expect(result.files).toHaveLength(1);
+    expect(result.jobs.map((j) => j.trigger.kind)).toEqual(["pull_request", "push", "cron"]);
+  });
+
+  test("the header sets up a Pipeline Schedule only for the Ops that need one", () => {
+    const yaml = generateGitlabOpPipeline([
+      { name: "tf-plan", trigger: { kind: "pull_request", branches: ["main"] } },
+      { name: "tf-apply", trigger: { kind: "push", branches: ["main"] } },
+    ]).files[0].yaml;
+    // No cron Op here, so nothing has to be created in Settings > CI/CD.
+    expect(yaml).not.toContain("Pipeline Schedule");
+    expect(yaml).toContain("merge_request_event onto main");
+    expect(yaml).toContain("push to main");
+  });
+
+  test("a branch name that would break out of the rule expression is refused by name", () => {
+    // A `rules:` if-expression is a string GitLab parses; a quote in a branch
+    // name would end it early and silently change which pipelines match.
+    expect(() =>
+      generateGitlabOpPipeline([
+        { name: "tf-plan", trigger: { kind: "pull_request", branches: ['main" || $CI_PIPELINE_SOURCE == "push'] } },
+      ]),
+    ).toThrow(/branch/i);
   });
 });
 
-describe("generateGitlabOpPipeline: no comment finding mode (#2231)", () => {
-  test("findingMode comment is refused by name, even on a cron trigger GitLab does support", () => {
-    const specs: ScheduledOpSpec[] = [
-      { name: "app-plan", schedule: "0 6 * * *", findingMode: "comment" },
-    ];
-    expect(() => generateGitlabOpPipeline(specs)).toThrow(
-      /Scheduled Op "app-plan".*findingMode "comment".*GitLab has no pull_request event/s,
-    );
+/**
+ * #2231's finding mode, now that there is a GitLab merge-request note
+ * activity to spend it (#2256). The blanket refusal this replaces was about
+ * chant having no way to post the note; what remains is the same constraint
+ * github already has — the mode posts onto the merge request that triggered
+ * the run, so it needs a trigger that has one.
+ */
+describe("generateGitlabOpPipeline: the comment finding mode on a merge request (#2231, #2256)", () => {
+  test("findingMode comment is accepted on a pull_request trigger", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
+    ]);
+    expect(result.jobs[0].findingMode).toBe("comment");
+    const job = parseYAML(result.files[0].yaml)["app-plan"] as { rules: Array<{ if: string }> };
+    expect(job.rules[0].if).toContain("merge_request_event");
+  });
+
+  test("the header names the token the note is written with", () => {
+    const yaml = generateGitlabOpPipeline([
+      { name: "app-plan", trigger: { kind: "pull_request" }, findingMode: "comment" },
+    ]).files[0].yaml;
+    expect(yaml).toContain("GITLAB_TOKEN");
+  });
+
+  test("findingMode comment on a cron trigger is refused, because a schedule has no merge request", () => {
+    expect(() =>
+      generateGitlabOpPipeline([{ name: "app-plan", schedule: "0 6 * * *", findingMode: "comment" }]),
+    ).toThrow(/findingMode "comment".*trigger is "cron"/s);
   });
 
-  test("the refusal names the modes GitLab does have", () => {
-    const specs: ScheduledOpSpec[] = [{ name: "app-plan", schedule: "0 6 * * *", findingMode: "comment" }];
-    expect(() => generateGitlabOpPipeline(specs)).toThrow(
-      /findingMode "issue" or "merge-request"/,
+  test("findingMode comment on a push trigger is refused, naming the trigger", () => {
+    expect(() =>
+      generateGitlabOpPipeline([
+        { name: "app-plan", trigger: { kind: "push" }, findingMode: "comment" },
+      ]),
+    ).toThrow(/findingMode "comment".*trigger is "push"/s);
+  });
+});
+
+/**
+ * #2243's green-gated apply, in the two surfaces GitLab has: the job's own
+ * log, and an artifact. There is no step summary to write to and no
+ * cross-job output to publish, so there is also no follow-up job.
+ */
+describe("generateGitlabOpPipeline: a gated apply is a green run (#2243, #2256)", () => {
+  function applyJob(): Record<string, unknown> {
+    const result = generateGitlabOpPipeline([
+      { name: "app-apply", trigger: { kind: "push", branches: ["main"] } },
+    ]);
+    return parseYAML(result.files[0].yaml)["app-apply"] as Record<string, unknown>;
+  }
+
+  test("the push job maps the gated exit code and nothing else", () => {
+    expect((applyJob().script as string[]).at(-1)).toBe("chant run app-apply --gated-exit 0");
+  });
+
+  test("the pending gate is written to a path the job also publishes as an artifact", () => {
+    const job = applyJob();
+    expect((job.variables as Record<string, string>).CHANT_GATE_SUMMARY).toBe(
+      "chant-gate-app-apply.md",
     );
+    expect(job.artifacts).toEqual({
+      when: "always",
+      paths: ["chant-gate-app-apply.md"],
+      expire_in: "30 days",
+    });
+  });
+
+  test("no other trigger is gated: a plan or a watch that stops is a signal, not noise", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "app-plan", trigger: { kind: "pull_request" } },
+      { name: "nightly", schedule: "0 6 * * *" },
+    ]);
+    const parsed = parseYAML(result.files[0].yaml);
+    for (const name of ["app-plan", "nightly"]) {
+      const job = parsed[name] as Record<string, unknown>;
+      expect((job.script as string[]).at(-1)).toBe(`chant run ${name}`);
+      expect(job.artifacts).toBeUndefined();
+      expect(job.variables).toBeUndefined();
+    }
   });
 });
 
@@ -161,11 +318,141 @@ describe("generateGitlabOpPipeline: setup steps and additive permissions (#2242)
     ]);
   });
 
-  test("refuses additive permissions by name, and points at GitLab's own OIDC surface", () => {
+  /**
+   * `id-token: write` is the one additive scope that has a GitLab meaning
+   * (#2256): the refusal it replaces already named `id_tokens:` as the shape
+   * to reach for, and this reaches for it rather than describing it. Every
+   * other scope is still refused, because GitLab has no per-job token-scope
+   * mapping to put it in.
+   */
+  test("id-token: write becomes an id_tokens declaration, GitLab's own OIDC surface", () => {
+    const result = generateGitlabOpPipeline([
+      {
+        name: "app-apply",
+        trigger: { kind: "push", branches: ["main"] },
+        permissions: { "id-token": "write" },
+      },
+    ]);
+    const job = parseYAML(result.files[0].yaml)["app-apply"] as Record<string, unknown>;
+    expect(job.id_tokens).toEqual({ CHANT_ID_TOKEN: { aud: "$CI_SERVER_URL" } });
+  });
+
+  test("an Op that adds no permissions declares no id_tokens", () => {
+    const result = generateGitlabOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }]);
+    const job = parseYAML(result.files[0].yaml)["actions-audit"] as Record<string, unknown>;
+    expect(job.id_tokens).toBeUndefined();
+  });
+
+  test("id-token: read is refused: GitLab either mints the token or does not", () => {
+    expect(() =>
+      generateGitlabOpPipeline([
+        { name: "actions-audit", schedule: "0 6 * * *", permissions: { "id-token": "read" } },
+      ]),
+    ).toThrow(/id-token: read/);
+  });
+
+  test("any other additive scope is still refused by name", () => {
     expect(() =>
       generateGitlabOpPipeline([
-        { name: "actions-audit", schedule: "0 6 * * *", permissions: { "id-token": "write" } },
+        { name: "actions-audit", schedule: "0 6 * * *", permissions: { "pull-requests": "write" } },
       ]),
-    ).toThrow(/adds permissions \{ id-token: write \}.*id_tokens:/s);
+    ).toThrow(/adds permission "pull-requests: write".*no per-job token-scope/s);
+  });
+});
+
+/**
+ * chant #2257 — the one option of the three that GitLab actually has. An
+ * environment is a project object here too, with the same two fields on the
+ * job and a protected-environment approval rule behind it, so the reviewer
+ * gate the option exists for is expressible and is emitted rather than
+ * refused. What is not expressible is the protection itself, which is a
+ * project setting, so the header names it the way it already names the
+ * schedule to create.
+ */
+describe("generateGitlabOpPipeline: a deployment environment (#2257)", () => {
+  const AUDIT: ScheduledOpSpec = { name: "actions-audit", schedule: "0 6 * * *", findingMode: "issue" };
+
+  /**
+   * The document a cron spec with no `environment` emits. #2257 pinned this to
+   * prove its option is additive; #2256 moved two lines of it and it is
+   * re-pinned rather than loosened, so it still proves the same thing.
+   *
+   * What moved: the header's opening paragraph, because a merge_request_event
+   * or push job needs no Pipeline Schedule and the cron instructions are now
+   * printed only for the Ops that do; and `resource_group`, which every job
+   * gains as GitLab's stand-in for github's per-Op concurrency group. The
+   * cron job's own rule, script and stage are byte-for-byte what they were.
+   */
+  const YAML_BEFORE_2257 =
+    [
+      "# chant Ops (#927, #2084) — one job per Op, each selected by its own",
+      "# rules:. A merge_request_event or push job needs no setup; its rule",
+      "# fires on the event itself.",
+      "#",
+      "# GitLab has no in-file cron. Create one Pipeline Schedule per cron Op",
+      "# below (Settings > CI/CD > Schedules): set its cron to the value noted",
+      "# here and its CHANT_SCHEDULED_OP CI/CD variable to the Op's name, so only",
+      "# that job runs on that schedule.",
+      "#",
+      '#   actions-audit: cron "0 6 * * *", CHANT_SCHEDULED_OP="actions-audit", finding-mode issue' +
+        " — needs a GITLAB_TOKEN CI/CD variable (masked, scope: api)",
+      "",
+      "stages:",
+      "  - scheduled-ops",
+      "",
+      "actions-audit:",
+      "  stage: scheduled-ops",
+      "  image: node:22-slim",
+      "  resource_group: actions-audit",
+      "  rules:",
+      `    - if: '$CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP == "actions-audit"'`,
+      "  script:",
+      "    - chant run actions-audit",
+    ].join("\n") + "\n";
+
+  test("a spec with no environment emits the bytes it emitted before the option existed", () => {
+    expect(generateGitlabOpPipeline([AUDIT]).files[0].yaml).toBe(YAML_BEFORE_2257);
+  });
+
+  test("maps it onto GitLab's own environment: key, with the url when there is one", () => {
+    const spec: ScheduledOpSpec = {
+      ...AUDIT,
+      environment: { name: "production", url: "https://app.example.com" },
+    };
+    const job = parseYAML(generateGitlabOpPipeline([spec]).files[0].yaml)["actions-audit"] as {
+      environment?: Record<string, string>;
+    };
+    expect(job.environment).toEqual({ name: "production", url: "https://app.example.com" });
+  });
+
+  test("names the environment to protect in the header, beside the schedule to create", () => {
+    const spec: ScheduledOpSpec = { ...AUDIT, environment: { name: "production" } };
+    const yaml = generateGitlabOpPipeline([spec]).files[0].yaml;
+    expect(yaml).toContain('deploys to environment "production"');
+    expect(yaml).toContain("Settings > CI/CD > Protected environments");
+    // The approval rule is a project setting; this file can only bind the job
+    // to the environment, so the header says where the rule is set.
+    expect(yaml).toContain("require an approval before the job runs");
+  });
+
+  test("adding the environment changes only the header line and the job's own key", () => {
+    const spec: ScheduledOpSpec = { ...AUDIT, environment: { name: "production" } };
+    const after = generateGitlabOpPipeline([spec]).files[0].yaml;
+    const withoutHeaderLine = after
+      .split("\n")
+      .filter((line) => !line.startsWith("#     deploys to environment"))
+      .join("\n");
+    expect(withoutHeaderLine.replace("  environment:\n    name: production\n", "")).toBe(
+      YAML_BEFORE_2257,
+    );
+  });
+
+  test("refuses a blank name and a url that is neither absolute nor a variable expression", () => {
+    expect(() => generateGitlabOpPipeline([{ ...AUDIT, environment: { name: " " } }])).toThrow(
+      /environment has an empty `name`/,
+    );
+    expect(() =>
+      generateGitlabOpPipeline([{ ...AUDIT, environment: { name: "production", url: "/deploys" } }]),
+    ).toThrow(/neither an absolute http\(s\) URL nor a variable expression/);
   });
 });

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

@@ -1,86 +1,275 @@
 /**
- * Generate mode — scheduled Op → GitLab CI YAML (#927).
+ * Generate mode — Op → GitLab CI YAML (#927, #2084, #2256).
  *
  * The Op counterpart to `./generate-pipeline.ts` (#563): that module
  * synthesizes a deploy-time component graph as one `.gitlab-ci.yml`; this one
- * synthesizes a cron-triggered job per stateless Op. An Op's cadence is an
- * `OpSchedule` on the Op itself (`packages/core/src/op/types.ts`),
- * runtime-neutral data each reader interprets; this module is the reader that
- * turns it into a GitLab pipeline schedule (`WorkflowAuditOp`/
- * `PipelineAuditOp`/`ReconcileOp` all accept an optional `schedule` precisely
- * for this).
+ * synthesizes one job per Op, selected by its own `rules:`.
+ *
+ * What GitLab genuinely lacks is in-file cron. A schedule is a project-level
+ * object (Settings → CI/CD → Schedules) that runs the project's *existing*
+ * `.gitlab-ci.yml` with a chosen cron and CI/CD variables, so a cron-triggered
+ * Op becomes a job gated on `$CI_PIPELINE_SOURCE == "schedule"` plus a per-Op
+ * selector variable, and the generated file's header says what to set up. What
+ * GitLab does not lack, and what this generator wrongly refused until #2256,
+ * is the other two triggers (#2084): `$CI_PIPELINE_SOURCE` distinguishes
+ * `merge_request_event` from `push` on every pipeline, and `rules:` selects a
+ * job on either. So:
+ *
+ *  - `cron` → `$CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP ==
+ *    "<name>"`, unchanged;
+ *  - `pull_request` → `$CI_PIPELINE_SOURCE == "merge_request_event"`, with the
+ *    branch filter mapped to `$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, which is
+ *    the branch the merge request would merge INTO — the same thing github's
+ *    `on.pull_request.branches` filters on;
+ *  - `push` → `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH ==
+ *    "<branch>"`, defaulting to the same `main` github's generator assumes.
+ *
+ * Two or more branches are two or more rule entries, because `rules:` is an
+ * OR over its entries and a regex alternation would need every branch name
+ * escaped into a pattern.
+ *
+ * Every job carries a `resource_group`, GitLab's stand-in for github's per-Op
+ * `concurrency` group: one run at a time per Op, the next one queued rather
+ * than cancelled. On an apply job that is also what stops two runs racing for
+ * the same state lock.
+ *
+ * Unlike github, all of this lands in ONE file. A GitHub trigger is
+ * workflow-scoped, so an Op there needs its own workflow; a GitLab trigger is
+ * job-scoped, so the whole set is one document with one job apiece.
  *
- * Unlike GitHub Actions' per-workflow `on.schedule`, GitLab has no in-file
- * cron at all — a schedule is a project-level object (Settings → CI/CD →
- * Schedules) that runs the project's *existing* `.gitlab-ci.yml` with a
- * chosen cron and CI/CD variables. So every scheduled Op here becomes one
- * job in a single generated file, gated to run only under its own Pipeline
- * Schedule (`$CI_PIPELINE_SOURCE == "schedule"` plus a per-op selector
- * variable) — the cron itself is configured on the Pipeline Schedule, not in
- * this YAML, and the generated file's header comment states what to set up.
  * Each job runs exactly one invocation, `chant run <name>` by default — never
- * inlined audit/reconcile logic. The finding-mode itself is already baked
- * into the Op's own activity args at build time by the composite that
- * created it; GitLab has no per-job `permissions:` concept (unlike GitHub
- * Actions), and `findingMode: "comment"` is refused by name here because it
- * posts onto a GitHub pull-request event GitLab does not have (#2231), so a
- * non-`report` mode's write access comes from whatever
- * `GITLAB_TOKEN`/CI-CD-variable configuration the project already has —
- * this generator documents the requirement rather than fabricating a
- * variable nothing reads.
+ * inlined audit/reconcile logic. The finding-mode is already baked into the
+ * Op's own activity args at build time by the composite that created it; this
+ * generator only wires what the mode needs to act.
+ *
+ * `findingMode: "comment"` works here since #2256: `reconcilePr` writes a
+ * merge-request note when the run is a `merge_request_event` pipeline, by the
+ * same hidden-marker edit-in-place recipe it uses on a GitHub pull request.
+ * What survives of the old blanket refusal is the constraint github already
+ * has — the mode posts onto the merge request that triggered the run, so a
+ * cron or push job carrying it is refused by name at build time rather than
+ * emitted to fail at its Report step ({@link assertTriggerSupportsMode}).
+ * GitLab has no per-job `permissions:` concept, so the note's write access
+ * comes from a `GITLAB_TOKEN` CI/CD variable, which the header names.
+ *
+ * #2242's two per-Op options cross over one and a half times. A `setup` entry
+ * spelled `{ uses }` is a GitHub Actions marketplace action; GitLab CI has
+ * `script` and nothing else, so there is no shape to translate it into and it
+ * is refused by name. A `{ run }` entry translates exactly, and is emitted
+ * ahead of the `beforeScript` lines — in `script:` rather than
+ * `before_script:`, which is where `./generate-pipeline.ts` puts the same
+ * option's lines in this same lexicon, and which concatenates identically at
+ * run time. An additive `permissions` map has exactly one entry with a GitLab
+ * meaning: `id-token: write` becomes an `id_tokens:` declaration ({@link
+ * idTokensFor}), the OIDC surface the old refusal already named as the shape
+ * to reach for. Every other scope is still refused, because there is no
+ * per-job token-scope mapping to put it in and a silently dropped scope emits
+ * a job that reads as granted and runs with nothing.
  *
- * Neither of #2242's two per-Op options survives the crossing, and both are
- * refused by name rather than dropped. A `setup` entry spelled `{ uses }` is
- * a GitHub Actions marketplace action; GitLab CI has `script` and nothing
- * else, so there is no shape to translate it into and no way to approximate
- * `aws-actions/configure-aws-credentials` in a shell line. A `{ run }` entry
- * translates exactly, and is emitted ahead of the `beforeScript` lines, the
- * same position the github generator gives it. An additive `permissions` map
- * is refused for the same reason `permissions:` is absent here at all: GitLab
- * has no per-job token-scope mapping, and its OIDC surface is a different
- * declaration (`id_tokens:` with an `aud`, exchanged for cloud credentials by
- * the job itself) that chant does not generate. Ignoring the map would emit a
- * job that reads as having OIDC and runs with no credentials.
+ * A spec's `environment` (#2257) does cross, because GitLab has the concept
+ * under the same key and with the same two fields: `environment: { name, url
+ * }` on the job, an environment object in the project, and — on a protected
+ * environment — an approval rule that holds the deployment job until an
+ * approver releases it. So the reviewer gate the option exists for is
+ * expressible here, unlike the `uses` setup step above, and it is emitted
+ * rather than refused. What GitLab does not have is any way for this file to
+ * declare the protection: an environment's approval rules are project
+ * settings (Settings > CI/CD > Protected environments), exactly as GitHub's
+ * required reviewers are repository settings, so the generated header names
+ * the environment to protect the way it already names the schedule to create.
+ * chant's own gate (#2119) runs inside the job either way.
  *
- * The gated-apply mapping (#2243) has nothing to attach to here. It exists
- * because a push-to-main apply that stops at its gate exits 3 and paints the
- * branch red on every merge; this generator has no push pipeline at all,
- * refusing a `push` trigger by name (#2084) because a GitLab schedule is a
- * project-level cron object rather than an event. GitLab does have its own
- * equivalent of the mapping should one ever be wanted — `allow_failure:
- * { exit_codes: [3] }` turns one exit code into a warning rather than a
- * failure, without a flag on the invocation — so the day this generator
- * grows a push trigger, that is the shape to reach for rather than
- * `--gated-exit`.
+ * The gated apply (#2243) lands in the two surfaces GitLab has. `chant run`
+ * returns 3 when a run stops at an unapproved gate, so a push-to-default apply
+ * would paint the branch red on every merge until someone approves; the push
+ * job runs with `--gated-exit 0`, mapping that one outcome and nothing else.
+ * Where GitHub Actions gets the pending block on its run page through
+ * `GITHUB_STEP_SUMMARY`, GitLab has no step summary at all, so the job sets
+ * `CHANT_GATE_SUMMARY` to a path it also declares under `artifacts:` and the
+ * block is downloadable from the pipeline. The human render is already in the
+ * job log, since the invocation carries no `--json`. There is no follow-up
+ * notice job: it would need a forge API call and a token this generator does
+ * not require of a `report`-mode Op.
  */
 
 import { emitYAML } from "@intentius/chant/yaml";
 import { resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGitlabOpOptions,
+  OpEnvironment,
   OpFindingMode,
   OpPipelineJob,
   OpPipelineResult as GenerateGitlabOpResult,
+  OpTrigger,
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
 
+export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
+
+/** GitLab CI job names must be safe YAML keys; Op names are already kebab-case in every fixture, but normalize defensively (mirrors `./generate-pipeline.ts`'s `toJobName`). */
+function toJobName(opName: string): string {
+  return opName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+const DEFAULT_IMAGE = "node:22-slim";
+const STAGE = "scheduled-ops";
+
+/** The CI/CD variable a Pipeline Schedule sets to select which job it runs. */
+const SELECTOR_VAR = "CHANT_SCHEDULED_OP";
+
 /**
- * Refuse the two #2242 options GitLab cannot honour, by name and before any
- * YAML exists, and return the `run` setup lines that do translate. See the
- * module doc for why each one is a refusal rather than a silent drop.
+ * Default branch assumed for a `push` trigger with no `branches` override.
+ * The same value github's generator documents, for the same reason: this
+ * operates on a `ScheduledOpSpec` rather than a git checkout, so it cannot
+ * read a downstream project's actual default branch. Set `trigger.branches`
+ * explicitly on a project whose default branch is something else.
  */
-function gitlabSetupScript(spec: ScheduledOpSpec): string[] {
-  if (spec.permissions && Object.keys(spec.permissions).length > 0) {
-    const scopes = Object.entries(spec.permissions)
-      .map(([scope, value]) => `${scope}: ${value}`)
-      .join(", ");
+const DEFAULT_PUSH_BRANCH = "main";
+
+/** The pipeline source GitLab reports for a merge-request pipeline. */
+const MERGE_REQUEST_SOURCE = '$CI_PIPELINE_SOURCE == "merge_request_event"';
+
+/**
+ * The `id_tokens:` entry an `id-token: write` spec gets. The name is the
+ * environment variable the JWT lands in, which the job's own setup line reads
+ * (`aws sts assume-role-with-web-identity --web-identity-token
+ * "$CHANT_ID_TOKEN"`, or the provider's equivalent).
+ *
+ * `$CI_SERVER_URL` as the audience is GitLab's own documented default: an
+ * identity provider federated to a GitLab instance is registered with that
+ * instance's URL as its audience, and the variable expands to exactly that on
+ * gitlab.com and on a self-managed instance alike. A project whose provider
+ * was registered with some other audience edits the generated declaration.
+ */
+const ID_TOKEN_NAME = "CHANT_ID_TOKEN";
+const ID_TOKEN_AUDIENCE = "$CI_SERVER_URL";
+
+/**
+ * `chant run` returns 3 when a run stops at an unapproved gate; `--gated-exit
+ * 0` maps that one outcome to success (#2243). `push` only — a cron watch or
+ * a merge-request plan that stops at a gate is a signal, not noise on a merge.
+ */
+const GATED_EXIT_FLAG = ["--gated-exit", "0"];
+
+/** The variable core's `writeGatedRunSummary` writes the pending-gate block to when the forge sets no step summary (#2256). */
+const GATE_SUMMARY_VAR = "CHANT_GATE_SUMMARY";
+
+/** How long a pending-gate artifact is worth keeping: long enough to outlive the approval it is waiting for. */
+const GATE_ARTIFACT_EXPIRY = "30 days";
+
+/**
+ * Refuse a branch name that cannot be interpolated into a `rules:`
+ * if-expression. The expression is a string GitLab parses, so a `"` would end
+ * it early and a `$` would expand as a variable — either one silently changes
+ * which pipelines match the job, which is worse than not generating it.
+ */
+function assertBranchName(specName: string, branch: string): void {
+  if (branch.trim() === "") {
+    throw new Error(
+      `Scheduled Op "${specName}" has an empty branch filter. Name a branch, or drop the filter.`,
+    );
+  }
+  if (/["$\\]/.test(branch)) {
+    throw new Error(
+      `Scheduled Op "${specName}" filters on branch "${branch}", which carries a character this generator ` +
+        `cannot put in a GitLab \`rules:\` expression: a quote would end the expression early and a "$" ` +
+        `would expand as a CI/CD variable, either of which silently changes which pipelines run the job. ` +
+        `Name a branch without \`"\`, \`$\` or \`\\\`.`,
+    );
+  }
+}
+
+/**
+ * This trigger's `rules:` entries. Two or more branches are two or more
+ * entries: `rules:` is an OR over its list, which is how GitLab spells the
+ * alternation github expresses as a `branches:` array.
+ */
+function rulesFor(spec: ScheduledOpSpec, trigger: OpTrigger): Array<{ if: string }> {
+  switch (trigger.kind) {
+    case "cron":
+      return [{ if: `$CI_PIPELINE_SOURCE == "schedule" && $${SELECTOR_VAR} == "${spec.name}"` }];
+    case "pull_request": {
+      const branches = trigger.branches ?? [];
+      if (branches.length === 0) return [{ if: MERGE_REQUEST_SOURCE }];
+      return branches.map((branch) => {
+        assertBranchName(spec.name, branch);
+        return { if: `${MERGE_REQUEST_SOURCE} && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "${branch}"` };
+      });
+    }
+    case "push": {
+      const branches = trigger.branches?.length ? trigger.branches : [DEFAULT_PUSH_BRANCH];
+      return branches.map((branch) => {
+        assertBranchName(spec.name, branch);
+        return { if: `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "${branch}"` };
+      });
+    }
+  }
+}
+
+/**
+ * Refuse `findingMode: "comment"` on a trigger that has no merge request
+ * (#2231, #2256). The mode's activity reads the merge request out of the
+ * pipeline's own variables at run time, so a cron- or push-triggered job
+ * carrying it would generate fine and then fail on every run. Refusing here
+ * names the Op, the mode and the trigger at build time instead — the same
+ * refusal github's generator makes, on the same terms.
+ */
+function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: OpTrigger): void {
+  if (mode !== "comment" || trigger.kind === "pull_request") return;
+  throw new Error(
+    `Scheduled Op "${name}" has findingMode "comment", which posts its finding as a note on the merge ` +
+      `request that triggered the run, but its trigger is "${trigger.kind}". A ${trigger.kind} pipeline has ` +
+      `no merge request to post on. Give it a { kind: "pull_request" } trigger, or use findingMode "issue" ` +
+      `or "merge-request".`,
+  );
+}
+
+/**
+ * Turn a spec's additive `permissions` (#2242) into the one GitLab
+ * declaration that carries the same meaning, refusing everything else by name.
+ *
+ * `id-token: write` is that one: GitLab's OIDC surface is `id_tokens:`, a
+ * per-job declaration of a JWT the job exchanges for cloud credentials
+ * itself. `id-token: read` is refused rather than mapped, because GitLab
+ * either mints the token into the job or does not — there is no read-only
+ * half of it, and emitting the declaration for a spec that asked for read
+ * would hand the job more than it asked for.
+ *
+ * Every other scope is refused, unchanged from the pre-#2256 behaviour:
+ * GitLab has no per-job token-scope mapping at all, and a scope quietly
+ * dropped would emit a job that reads as granted and runs with nothing.
+ */
+function idTokensFor(spec: ScheduledOpSpec): Record<string, unknown> | undefined {
+  let wantsIdToken = false;
+  for (const [rawScope, value] of Object.entries(spec.permissions ?? {})) {
+    const scope = rawScope.trim();
+    if (scope === "id-token") {
+      if (value !== "write") {
+        throw new Error(
+          `Scheduled Op "${spec.name}" adds permission "id-token: ${value}", but GitLab either mints an ` +
+            `OIDC token into a job or does not — there is no read-only half of an \`id_tokens:\` ` +
+            `declaration. Ask for { "id-token": "write" }, or drop the option.`,
+        );
+      }
+      wantsIdToken = true;
+      continue;
+    }
     throw new Error(
-      `Scheduled Op "${spec.name}" adds permissions { ${scopes} }, but GitLab CI has no per-job token-scope ` +
-        `mapping — there is no \`permissions:\` key to add them to (#2242). Its OIDC surface is a separate ` +
-        `\`id_tokens:\` declaration the job exchanges for cloud credentials itself, which chant does not ` +
-        `generate. Drop the option here, or generate this Op for github.`,
+      `Scheduled Op "${spec.name}" adds permission "${scope}: ${value}", but GitLab CI has no per-job ` +
+        `token-scope mapping — there is no \`permissions:\` key to add it to (#2242). The one scope that ` +
+        `does cross over is "id-token": "write", which becomes an \`id_tokens:\` declaration. Drop the ` +
+        `option here, or generate this Op for github.`,
     );
   }
+  return wantsIdToken ? { [ID_TOKEN_NAME]: { aud: ID_TOKEN_AUDIENCE } } : undefined;
+}
+
+/**
+ * Refuse a `uses` setup step by name and return the `run` lines that do
+ * translate. See the module doc for why a marketplace action is a refusal
+ * rather than a silent drop.
+ */
+function gitlabSetupScript(spec: ScheduledOpSpec): string[] {
   const lines: string[] = [];
   (spec.setup ?? []).forEach((step, index) => {
     if ("uses" in step) {
@@ -95,30 +284,88 @@ function gitlabSetupScript(spec: ScheduledOpSpec): string[] {
   return lines;
 }
 
-export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
-
-/** GitLab CI job names must be safe YAML keys; Op names are already kebab-case in every fixture, but normalize defensively (mirrors `./generate-pipeline.ts`'s `toJobName`). */
-function toJobName(opName: string): string {
-  return opName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/**
+ * Validate a spec's `environment` (#2257) on GitLab's own terms. A GitLab job
+ * naming an environment that does not exist creates an unprotected one on
+ * first deploy rather than failing, so — as on github — the only shapes worth
+ * refusing at build time are the ones that could never bind: a blank name,
+ * and a `url` that is neither absolute nor a variable expression GitLab
+ * expands, which would render as a dead "View deployment" link.
+ */
+function assertGitlabEnvironment(name: string, environment: OpEnvironment): void {
+  const where = `Scheduled Op "${name}" environment`;
+  if (environment.name.trim() === "") {
+    throw new Error(
+      `${where} has an empty \`name\`. A GitLab environment is a project object, and its approval ` +
+        `rules live on that object rather than in this file, so a blank name resolves to nothing. ` +
+        `Give it the environment's name, or drop the option.`,
+    );
+  }
+  if (environment.url === undefined) return;
+  const url = environment.url.trim();
+  if (url === "") {
+    throw new Error(
+      `${where} "${environment.name}" has an empty \`url\`. Omit the field rather than setting it to "".`,
+    );
+  }
+  if (!/^https?:\/\//.test(url) && !url.includes("$")) {
+    throw new Error(
+      `${where} "${environment.name}" has \`url: "${environment.url}"\`, which is neither an absolute ` +
+        `http(s) URL nor a variable expression GitLab expands. It becomes the environment's own link, ` +
+        `so a relative path is a dead link on the environment page rather than an error anywhere.`,
+    );
+  }
 }
 
-const DEFAULT_IMAGE = "node:22-slim";
-const STAGE = "scheduled-ops";
+/**
+ * The follow-up line an Op with an `environment` adds under its own header
+ * line (#2257). The `environment:` key on the job binds it to the
+ * environment; it cannot declare the approval rule, which is a project
+ * setting, so the header says where that is set the same way it says where a
+ * schedule is created.
+ */
+function environmentLine(environment: OpEnvironment): string {
+  return (
+    `#     deploys to environment "${environment.name}" — protect it under Settings > CI/CD >` +
+    " Protected environments to require an approval before the job runs"
+  );
+}
 
-/** The CI/CD variable a Pipeline Schedule sets to select which job it runs. */
-const SELECTOR_VAR = "CHANT_SCHEDULED_OP";
+/** The artifact path a push job's pending-gate block is written to (#2243, #2256). */
+function gateSummaryPath(jobName: string): string {
+  return `chant-gate-${jobName}.md`;
+}
 
-/** One setup line per Op in the generated file's header comment. */
-function setupLine(spec: ScheduledOpSpec, cron: string, jobName: string, mode: OpFindingMode): string {
-  const tokenNote = mode === "report" ? "" : " — needs a GITLAB_TOKEN CI/CD variable (masked, scope: api)";
-  return `#   ${jobName}: cron "${cron}", ${SELECTOR_VAR}="${spec.name}", finding-mode ${mode}${tokenNote}`;
+/** One line per Op in the generated file's header comment, naming what fires it. */
+function headerLineFor(
+  spec: ScheduledOpSpec,
+  trigger: OpTrigger,
+  jobName: string,
+  mode: OpFindingMode,
+): string {
+  const tokenNote =
+    mode === "report" ? "" : " — needs a GITLAB_TOKEN CI/CD variable (masked, scope: api)";
+  switch (trigger.kind) {
+    case "cron":
+      return `#   ${jobName}: cron "${trigger.schedule}", ${SELECTOR_VAR}="${spec.name}", finding-mode ${mode}${tokenNote}`;
+    case "pull_request": {
+      const onto = trigger.branches?.length ? trigger.branches.join(", ") : "any branch";
+      return `#   ${jobName}: merge_request_event onto ${onto}, finding-mode ${mode}${tokenNote}`;
+    }
+    case "push": {
+      const branches = trigger.branches?.length ? trigger.branches : [DEFAULT_PUSH_BRANCH];
+      return (
+        `#   ${jobName}: push to ${branches.join(", ")}, finding-mode ${mode}${tokenNote}` +
+        ` — a gated apply stays green, its pending gate in the log and in ${gateSummaryPath(jobName)}`
+      );
+    }
+  }
 }
 
 /**
- * Synthesize one `.gitlab-ci.yml` job per scheduled Op, all in a single file
- * (GitLab has no per-file cron — see the module doc). Wired into core's Op
- * generate mode via the gitlab lexicon plugin's `generateOpPipeline`
- * (../plugin.ts).
+ * Synthesize one `.gitlab-ci.yml` job per Op, all in a single file (a GitLab
+ * trigger is job-scoped — see the module doc). Wired into core's Op generate
+ * mode via the gitlab lexicon plugin's `generateOpPipeline` (../plugin.ts).
  */
 export function generateGitlabOpPipeline(
   ops: ScheduledOpSpec[],
@@ -133,53 +380,76 @@ export function generateGitlabOpPipeline(
   const doc: Record<string, unknown> = { stages: [STAGE] };
   if (options.variables && Object.keys(options.variables).length > 0) doc.variables = options.variables;
 
-  const headerLines = [
-    "# Scheduled Ops (chant #927) — GitLab has no in-file cron. Create one",
-    "# Pipeline Schedule per Op below (Settings > CI/CD > Schedules): set its",
-    `# cron to the value noted here and its ${SELECTOR_VAR} CI/CD variable to`,
-    "# the Op's name, so only that job runs on that schedule.",
-    "#",
-  ];
+  const opLines: string[] = [];
+  let anyCron = false;
 
   for (const spec of ops) {
     const setupScript = gitlabSetupScript(spec);
+    const idTokens = idTokensFor(spec);
     const findingMode = spec.findingMode ?? "report";
-    if (findingMode === "comment") {
-      // The mode posts onto the pull request that triggered the run (#2231),
-      // read out of the GitHub Actions event payload by `reconcilePr`. GitLab
-      // has neither that event model nor that payload, and core carries no
-      // GitLab API client that would post the merge-request note instead, so
-      // this refuses the mode by name rather than emitting a job whose finding
-      // step fails on every pipeline.
-      throw new Error(
-        `Scheduled Op "${spec.name}" has findingMode "comment", which posts its finding on the pull request ` +
-          `that triggered the run. GitLab has no pull_request event and chant has no GitLab merge-request ` +
-          `note activity (#2231). Use findingMode "issue" or "merge-request" here, or generate this Op for ` +
-          `github.`,
-      );
-    }
     const trigger = resolveOpTrigger(spec);
-    if (trigger.kind !== "cron") {
-      throw new Error(
-        `Scheduled Op "${spec.name}" has a "${trigger.kind}" trigger, but GitLab has no pull_request/push event model ` +
-          `(#2084) — only a project-level Pipeline Schedule (cron). Give it a cron trigger, or generate it for github/forgejo instead.`,
-      );
-    }
+    assertTriggerSupportsMode(spec.name, findingMode, trigger);
+    if (trigger.kind === "cron") anyCron = true;
+
     const jobName = toJobName(spec.name);
     jobs.push({ jobName, op: spec.name, trigger, findingMode });
-    headerLines.push(setupLine(spec, trigger.schedule, jobName, findingMode));
+    opLines.push(headerLineFor(spec, trigger, jobName, findingMode));
+    if (spec.environment) {
+      assertGitlabEnvironment(spec.name, spec.environment);
+      opLines.push(environmentLine(spec.environment));
+    }
 
+    // A push job is the one a gate would otherwise paint red on every merge
+    // (#2243). Every other trigger keeps the plain one-line invocation.
+    const gated = trigger.kind === "push";
     const runParts = runCommand.map((part) => part.replace("{name}", spec.name));
-    const script = [...setupScript, ...beforeScript, runParts.join(" "), ...extraScript];
+    const invocation = gated ? [...runParts, ...GATED_EXIT_FLAG] : runParts;
+    const gateSummary = gateSummaryPath(jobName);
 
     doc[jobName] = {
       stage: STAGE,
       image,
-      rules: [{ if: `$CI_PIPELINE_SOURCE == "schedule" && $${SELECTOR_VAR} == "${spec.name}"` }],
-      script,
+      // GitLab's stand-in for github's per-Op concurrency group: queue the
+      // next run rather than cancel the current one.
+      resource_group: jobName,
+      ...(idTokens ? { id_tokens: idTokens } : {}),
+      ...(spec.environment
+        ? {
+            environment: {
+              name: spec.environment.name,
+              ...(spec.environment.url === undefined ? {} : { url: spec.environment.url }),
+            },
+          }
+        : {}),
+      ...(gated ? { variables: { [GATE_SUMMARY_VAR]: gateSummary } } : {}),
+      rules: rulesFor(spec, trigger),
+      script: [...setupScript, ...beforeScript, invocation.join(" "), ...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: [gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
+        : {}),
     };
   }
 
+  const headerLines = [
+    "# chant Ops (#927, #2084) — one job per Op, each selected by its own",
+    "# rules:. A merge_request_event or push job needs no setup; its rule",
+    "# fires on the event itself.",
+  ];
+  if (anyCron) {
+    headerLines.push(
+      "#",
+      "# GitLab has no in-file cron. Create one Pipeline Schedule per cron Op",
+      "# below (Settings > CI/CD > Schedules): set its cron to the value noted",
+      `# here and its ${SELECTOR_VAR} CI/CD variable to the Op's name, so only`,
+      "# that job runs on that schedule.",
+    );
+  }
+  headerLines.push("#", ...opLines);
+
   const sections: string[] = [];
   sections.push("stages:" + emitYAML(doc.stages, 1));
   if (doc.variables) sections.push("variables:" + emitYAML(doc.variables, 1));

package/src/plugin.ts

@@ -30,7 +30,8 @@ export const gitlabPlugin: LexiconPlugin = {
   auditCatalog: () => gitlabAuditCatalog,
   // Generate mode (#688): synthesize a .gitlab-ci.yml from the component graph.
   generateComponentPipeline: (components, options) => generateGitlabPipeline(components, options),
-  // Generate mode, Op counterpart (#927): scheduled Op → GitLab CI job.
+  // Generate mode, Op counterpart (#927): an Op → one GitLab CI job, on a
+  // Pipeline Schedule, a merge request or a push (#2084, #2256).
   generateOpPipeline: (ops, options) => generateGitlabOpPipeline(ops, options),
   // Self-upgrade: where the pinned GitLab schema version lives + its upstream (#685).
   upstreamPin: {