@intentius/chant-lexicon-gitlab 0.124.23 → 0.124.24

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

@@ -18,6 +18,12 @@
  *
  * A `pr-review` wave (#3684) adds `<name>-record-plans`, run in merge request
  * pipelines only, which records the digests the merge request's head plans.
+ *
+ * `runner` (on the spec, a wave or a job group, #3914) is the job's `tags:`; a
+ * GitHub runner group is a spec error here. A wave's `jobs` renders its
+ * deciding job with the wave's own settings and a job per group (per share of
+ * a group) with the group's: its tags, environment, variables over the
+ * wave's, setup after the wave's, and `id_tokens:` from its `idTokens`.
  */
 import { type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAG9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAqEvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAkBH,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACjH,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAG9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAyFvH"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "c1c4496f3369b8efe07d618e66776e95e8e891bf7fc0f7fc2b4885a597a79ce4",
+    "manifest.json": "a373d4af5482711a1b501907a60d10deb1e50ea9dcbf70941eb4b1e54126ace0",
     "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": "991e8b6176e06983389ce0662a1338b701f1e93ceedc0d815430d603a3d68885"
+  "composite": "3342dfc812c8e79be300ba1c27098440d0f91be83a87ec2f36e6d355caafe1d8"
 }

package/dist/manifest.json

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

package/package.json

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

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

@@ -0,0 +1,86 @@
+# chant Op waves "migrations": one stage per wave, each needing the one before.
+# A wave that waits at its gate exits 3 and stops the waves after it; approve the
+# digest it prints, then retry the job.
+
+stages:
+  - wave-1-dev
+  - wave-2-prod
+
+wave-1-dev:
+  stage: wave-1-dev
+  image: node:22
+  tags:
+    - docker
+    - dev
+  resource_group: migrations-dev
+  variables:
+    GIT_DEPTH: '0'
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
+  script:
+    - chant run wave --spec waves.json --wave 1
+
+wave-2-prod-decide:
+  stage: wave-2-prod
+  image: node:22
+  tags:
+    - plan
+  resource_group: migrations-prod
+  id_tokens:
+    PLAN_TOKEN:
+      aud: plan.example
+  variables:
+    GIT_DEPTH: '0'
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
+  needs:
+    - wave-1-dev
+  script:
+    - chant run wave --spec waves.json --wave 2 --decide
+  artifacts:
+    when: always
+    paths:
+      - .chant/op-waves/migrations/wave-2.json
+    expire_in: '30 days'
+
+wave-2-prod-us:
+  stage: wave-2-prod
+  image: node:22
+  tags:
+    - us-apply
+  resource_group: migrations-prod
+  environment:
+    name: prod-us
+  id_tokens:
+    CLOUD_TOKEN:
+      aud: us.example
+  variables:
+    GIT_DEPTH: '0'
+    REGION: us
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
+  needs:
+    - wave-2-prod-decide
+  script:
+    - echo us
+    - chant run wave --spec waves.json --wave 2 --group us
+
+wave-2-prod-eu:
+  stage: wave-2-prod
+  image: node:22
+  tags:
+    - eu-apply
+  resource_group: migrations-prod
+  environment:
+    name: prod-eu
+  id_tokens:
+    CLOUD_TOKEN:
+      aud: eu.example
+  variables:
+    GIT_DEPTH: '0'
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"'
+  needs:
+    - wave-2-prod-decide
+  script:
+    - chant run wave --spec waves.json --wave 2 --group eu

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

@@ -69,3 +69,43 @@ describe("a wave's environment is checked as an Op's is (#3765)", () => {
     expect(generateGitlabOpWavesPipeline(one({ name: "dev", url: "$CI_ENVIRONMENT_URL" }), { specFile: "waves.json" }).files[0]!.yaml).toContain("url: '$CI_ENVIRONMENT_URL'");
   });
 });
+
+describe("a runner per wave and job groups per wave (#3914)", () => {
+  const grouped: OpWavesSpec = {
+    ...spec,
+    runner: "plan",
+    waves: [
+      { name: "dev", runs: [{ target: "dev" }], gate: "never", runner: ["docker", "dev"] },
+      {
+        name: "prod",
+        runs: [{ target: "us/a" }, { target: "eu/a" }],
+        idTokens: { PLAN_TOKEN: "plan.example" },
+        jobs: [
+          { name: "us", runs: ["us/*"], runner: "us-apply", environment: { name: "prod-us" }, variables: { REGION: "us" }, setup: [{ run: "echo us" }], idTokens: { CLOUD_TOKEN: "us.example" } },
+          { name: "eu", runs: ["eu/*"], runner: "eu-apply", environment: { name: "prod-eu" }, idTokens: { CLOUD_TOKEN: "eu.example" } },
+        ],
+      },
+    ],
+  };
+
+  test("the rendered pipeline matches its golden", async () => {
+    await expect(generateGitlabOpWavesPipeline(grouped, { specFile: "waves.json" }).files[0]!.yaml).toMatchFileSnapshot("./__golden__/op-waves-jobs.yml");
+  });
+
+  test("tags, environment, id_tokens, variables and the group's command on each job", () => {
+    const yaml = generateGitlabOpWavesPipeline(grouped, { specFile: "waves.json" }).files[0]!.yaml;
+    expect(yaml).toMatch(/wave-1-dev:\n\s+stage: wave-1-dev\n\s+image: node:22\n\s+tags:\n\s+- docker\n\s+- dev\n/);
+    expect(yaml).toMatch(/wave-2-prod-decide:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- plan\n\s+resource_group: migrations-prod\n\s+id_tokens:\n\s+PLAN_TOKEN:\n\s+aud: plan.example\n/);
+    expect(yaml).toMatch(
+      /wave-2-prod-us:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- us-apply\n\s+resource_group: migrations-prod\n\s+environment:\n\s+name: prod-us\n\s+id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: us.example\n\s+variables:\n\s+GIT_DEPTH: '0'\n\s+REGION: us\n[\s\S]*?needs:\n\s+- wave-2-prod-decide\n\s+script:\n\s+- echo us\n\s+- chant run wave --spec waves.json --wave 2 --group us\n/,
+    );
+    expect(yaml).toMatch(/wave-2-prod-eu:[\s\S]*?id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: eu.example\n/);
+    expect(yaml).not.toContain("_AUDIENCE");
+  });
+
+  test("a runner group is a spec error naming the wave and the field", () => {
+    const withGroup = (runner: { group: string }) => ({ ...grouped, waves: [grouped.waves[0]!, { ...grouped.waves[1]!, jobs: [{ ...grouped.waves[1]!.jobs![0]!, runner }, grouped.waves[1]!.jobs![1]!] }] });
+    expect(() => generateGitlabOpWavesPipeline(withGroup({ group: "apply" }), { specFile: "waves.json" })).toThrow(/wave "prod" job group "us" runner is the runner group "apply", which only GitHub has/);
+    expect(() => generateGitlabOpWavesPipeline({ ...spec, runner: { group: "apply" } }, { specFile: "waves.json" })).toThrow(/Op waves "migrations": runner is the runner group/);
+  });
+});

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

@@ -18,22 +18,31 @@
  *
  * A `pr-review` wave (#3684) adds `<name>-record-plans`, run in merge request
  * pipelines only, which records the digests the merge request's head plans.
+ *
+ * `runner` (on the spec, a wave or a job group, #3914) is the job's `tags:`; a
+ * GitHub runner group is a spec error here. A wave's `jobs` renders its
+ * deciding job with the wave's own settings and a job per group (per share of
+ * a group) with the group's: its tags, environment, variables over the
+ * wave's, setup after the wave's, and `id_tokens:` from its `idTokens`.
  */
 
 import {
   assertGitlabBranch,
   assertGitlabEnvironment,
+  assertRunnerLabels,
   CI_IMAGE,
   environmentDoc,
   GITLAB_FULL_HISTORY,
   GITLAB_MERGE_REQUEST_SOURCE,
   GITLAB_SCHEDULE_SOURCE,
+  gitlabIdTokensDoc,
   gitlabPushRule,
   gitlabSetupScript,
+  gitlabTags,
   nonEmpty,
   pushBranches,
 } from "@intentius/chant/ci-jobs";
-import { opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { opWaveGroupOf, opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
 import { emitGitlabFile } from "./ci-jobs";
 
@@ -49,6 +58,18 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
   // The setup and environment each wave's jobs carry, checked as an Op's are.
   const setupOf = spec.waves.map((wave) => gitlabSetupScript(`${subject} wave "${wave.name}"`, wave.setup));
   for (const wave of spec.waves) if (wave.environment) assertGitlabEnvironment(`${spec.name}/${wave.name}`, wave.environment);
+  // #3914: GitLab picks a runner by tags, and each job group carries its own setup and environment.
+  assertRunnerLabels(subject, "runner", spec.runner, "GitLab");
+  const groupSetup = new Map<string, string[]>();
+  for (const wave of spec.waves) {
+    assertRunnerLabels(subject, `wave "${wave.name}" runner`, wave.runner, "GitLab");
+    for (const group of wave.jobs ?? []) {
+      assertRunnerLabels(subject, `wave "${wave.name}" job group "${group.name}" runner`, group.runner, "GitLab");
+      if (group.environment) assertGitlabEnvironment(`${spec.name}/${wave.name}/${group.name}`, group.environment);
+      groupSetup.set(`${wave.name}/${group.name}`, gitlabSetupScript(`${subject} wave "${wave.name}" job group "${group.name}"`, group.setup));
+    }
+  }
+  const specTags = gitlabTags(spec.runner);
 
   const byReview = spec.waves.some((w) => w.approval === "pr-review");
   const stages = [...(byReview ? ["plans"] : []), ...spec.waves.map((wave, i) => `wave-${i + 1}-${wave.name}`)];
@@ -62,6 +83,7 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
       {
         stage: "plans",
         image,
+        ...(specTags ? { tags: specTags } : {}),
         variables: { ...GITLAB_FULL_HISTORY },
         rules: [{ if: GITLAB_MERGE_REQUEST_SOURCE }],
         script: [...(options.beforeScript ?? []), ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ")],
@@ -70,15 +92,21 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
   }
   for (const job of jobs) {
     const wave = spec.waves[job.wave - 1]!;
-    const setup = setupOf[job.wave - 1]!;
+    const group = opWaveGroupOf(spec, job);
+    const setup = [...setupOf[job.wave - 1]!, ...(group ? groupSetup.get(`${wave.name}/${group.name}`)! : [])];
+    const tags = gitlabTags(group?.runner ?? wave.runner ?? spec.runner);
+    const environment = group?.environment ?? wave.environment;
+    const idTokens = gitlabIdTokensDoc(group?.idTokens ?? wave.idTokens);
     entries.push([
       job.jobName,
       {
         stage: stages[job.wave - 1 + (byReview ? 1 : 0)],
         image,
+        ...(tags ? { tags } : {}),
         resource_group: `${spec.name}-${wave.name}`,
-        ...(wave.environment ? { environment: environmentDoc(wave.environment) } : {}),
-        variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}) },
+        ...(environment ? { environment: environmentDoc(environment) } : {}),
+        ...(idTokens ? { id_tokens: idTokens } : {}),
+        variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}), ...(group?.variables ?? {}) },
         rules,
         ...(job.needs.length > 0 ? { needs: job.needs } : {}),
         script: [...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
@@ -92,6 +120,7 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
       {
         stage: "resume",
         image,
+        ...(specTags ? { tags: specTags } : {}),
         rules: [{ if: GITLAB_SCHEDULE_SOURCE }],
         script: [...(options.beforeScript ?? []), opWavesResumeCommand(spec).join(" ")],
       },