@intentius/chant-lexicon-github 0.124.22 → 0.124.24

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

@@ -27,6 +27,13 @@
  * With `notify` on the spec (#3761), the workflow maps each variable it names
  * from the repository secret of the same name, so a wave job can post to
  * Slack, Teams or a signed webhook. `options.variables` wins over the mapping.
+ *
+ * `runner` (on the spec, a wave or a job group, #3914) is the job's `runs-on`.
+ * 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 runner,
+ * environment, variables over the wave's, setup after the wave's, and id
+ * tokens. A job with id tokens gets `permissions:` of its own, the
+ * workflow's plus `id-token: write`, and each audience as `<NAME>_AUDIENCE`.
  */
 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAqD,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACnH,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAe9F,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAW,CAAC;AAEvC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAgDpI;AAyCD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAoE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAClI,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAgB9F,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAW,CAAC;AAEvC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CA2DpI;AA0CD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "585227ba9a53209d3de6e7c24fb49677eb7a135c1cc6a34c05cf57a803ad966a",
+    "manifest.json": "ab329d49ebddfa547afccf09a39cb746378211e9292b9d6f88db95d5f5f357e0",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "0ead95536e947ddfb98a5acf0ddb88547913b5a53a342df67711c59266f84b3e",
     "rules/deprecated-action-version.ts": "a9ba7cc924ff1c7055110416d8989273690415bfb5e8dcc32dc9431b9351f5ca",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "06b11832064ffc0aa7684de96e4f6d0294b892d9e5fce9229c5ab9d793cd4413"
+  "composite": "680c4d4083a0fe1a921a6bd565971dec440c393e60b6dbdeec3564d46567810f"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.124.22",
+  "version": "0.124.24",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.124.22",
+  "version": "0.124.24",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,6 +61,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.22"
+    "@intentius/chant": "^0.124.24"
   }
 }

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

@@ -0,0 +1,135 @@
+name: migrations
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch: {}
+
+concurrency:
+  group: migrations
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  wave-1-dev:
+    runs-on:
+      - self-hosted
+      - dev
+    container: node:22
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Plan, gate and apply wave 1 (dev)
+        run: chant run wave --spec waves.json --wave 1
+  wave-2-prod-decide:
+    runs-on: plan
+    needs:
+      - wave-1-dev
+    container: node:22
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      STAGE: apply
+      PLAN_TOKEN_AUDIENCE: plan.example
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Plan wave 2 (prod) and decide its gate
+        run: chant run wave --spec waves.json --wave 2 --decide
+      - name: Keep wave 2's decision
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: migrations-wave-2-decision
+          path: .chant/op-waves/migrations/wave-2.json
+          if-no-files-found: ignore
+          include-hidden-files: true
+          overwrite: true
+  wave-2-prod-us-share-1:
+    runs-on:
+      group: prod-apply
+      labels:
+        - linux
+    needs:
+      - wave-2-prod-decide
+    container: node:22
+    environment:
+      name: prod-us
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      STAGE: apply
+      REGION: us
+      CLOUD_TOKEN_AUDIENCE: us.example
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Download wave 2's decision
+        uses: actions/download-artifact@v4
+        with:
+          name: migrations-wave-2-decision
+          path: .chant/op-waves/migrations
+      - run: echo us
+      - name: Apply share 1 of job group us of wave 2 (prod)
+        run: chant run wave --spec waves.json --wave 2 --group us --share 1
+  wave-2-prod-us-share-2:
+    runs-on:
+      group: prod-apply
+      labels:
+        - linux
+    needs:
+      - wave-2-prod-decide
+    container: node:22
+    environment:
+      name: prod-us
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      STAGE: apply
+      REGION: us
+      CLOUD_TOKEN_AUDIENCE: us.example
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Download wave 2's decision
+        uses: actions/download-artifact@v4
+        with:
+          name: migrations-wave-2-decision
+          path: .chant/op-waves/migrations
+      - run: echo us
+      - name: Apply share 2 of job group us of wave 2 (prod)
+        run: chant run wave --spec waves.json --wave 2 --group us --share 2
+  wave-2-prod-eu:
+    runs-on: eu-apply
+    needs:
+      - wave-2-prod-decide
+    container: node:22
+    environment:
+      name: prod-eu
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      STAGE: apply
+      PLAN_TOKEN_AUDIENCE: plan.example
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Download wave 2's decision
+        uses: actions/download-artifact@v4
+        with:
+          name: migrations-wave-2-decision
+          path: .chant/op-waves/migrations
+      - name: Apply job group eu of wave 2 (prod)
+        run: chant run wave --spec waves.json --wave 2 --group eu

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

@@ -74,3 +74,50 @@ describe("generateGithubOpWavesPipeline", () => {
     expect(() => generateGithubOpWavesPipeline({ ...waveLevel, hooks: { after: { apply: [{ command: ["./bin/smoke"], onFailure: "approve" }] } } }, { specFile: "waves.json" })).toThrow(/nothing left to hold/);
   });
 });
+
+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: ["self-hosted", "dev"] },
+      {
+        name: "prod",
+        runs: [{ target: "us/a" }, { target: "us/b" }, { target: "eu/a" }],
+        variables: { STAGE: "apply" },
+        idTokens: { PLAN_TOKEN: "plan.example" },
+        jobs: [
+          { name: "us", runs: ["us/*"], shares: 2, runner: { group: "prod-apply", labels: ["linux"] }, 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" } },
+        ],
+      },
+    ],
+  };
+
+  test("the rendered pipeline matches its golden", async () => {
+    await expect(generateGithubOpWavesPipeline(grouped, { specFile: "waves.json" }).files[0]!.yaml).toMatchFileSnapshot("./__golden__/op-waves-jobs.yml");
+  });
+
+  test("runs-on, environment, variables, id-token and the group's command on each job", () => {
+    const { files, jobs } = generateGithubOpWavesPipeline(grouped, { specFile: "waves.json" });
+    expect(jobs.map((j) => j.jobName)).toEqual(["wave-1-dev", "wave-2-prod-decide", "wave-2-prod-us-share-1", "wave-2-prod-us-share-2", "wave-2-prod-eu"]);
+    const yaml = files[0]!.yaml;
+    expect(yaml).toMatch(/wave-1-dev:\n\s+runs-on:\n\s+- self-hosted\n\s+- dev\n/);
+    expect(yaml).toMatch(
+      /wave-2-prod-decide:\n\s+runs-on: plan\n[\s\S]*?permissions:\n\s+contents: write\n\s+id-token: write\n\s+env:\n\s+STAGE: apply\n\s+PLAN_TOKEN_AUDIENCE: plan.example\n/,
+    );
+    expect(yaml).toMatch(
+      /wave-2-prod-us-share-1:\n\s+runs-on:\n\s+group: prod-apply\n\s+labels:\n\s+- linux\n\s+needs:\n\s+- wave-2-prod-decide\n\s+container: node:22\n\s+environment:\n\s+name: prod-us\n\s+permissions:\n\s+contents: write\n\s+id-token: write\n\s+env:\n\s+STAGE: apply\n\s+REGION: us\n\s+CLOUD_TOKEN_AUDIENCE: us.example\n/,
+    );
+    expect(yaml).toContain("- run: echo us\n      - name: Apply share 1 of job group us of wave 2 (prod)\n        run: chant run wave --spec waves.json --wave 2 --group us --share 1\n");
+    // A group with no id tokens of its own gets the wave's.
+    expect(yaml).toMatch(/wave-2-prod-eu:\n\s+runs-on: eu-apply\n[\s\S]*?name: prod-eu\n\s+permissions:\n\s+contents: write\n\s+id-token: write\n\s+env:\n\s+STAGE: apply\n\s+PLAN_TOKEN_AUDIENCE: plan.example\n/);
+    expect(yaml).toContain("run: chant run wave --spec waves.json --wave 2 --group eu\n");
+  });
+
+  test("the spec's runner is the resume and record-plans jobs' too", () => {
+    const { files } = generateGithubOpWavesPipeline({ ...spec, runner: "plan", resume: { schedule: "*/10 * * * *" }, waves: spec.waves.map((w) => ({ ...w, approval: "pr-review" as const })) }, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual(["migrations.yml", "migrations-resume.yml", "migrations-plans.yml"]);
+    for (const f of files) expect(f.yaml).not.toContain("ubuntu-latest");
+  });
+});

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

@@ -27,9 +27,16 @@
  * With `notify` on the spec (#3761), the workflow maps each variable it names
  * from the repository secret of the same name, so a wave job can post to
  * Slack, Teams or a signed webhook. `options.variables` wins over the mapping.
+ *
+ * `runner` (on the spec, a wave or a job group, #3914) is the job's `runs-on`.
+ * 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 runner,
+ * environment, variables over the wave's, setup after the wave's, and id
+ * tokens. A job with id tokens gets `permissions:` of its own, the
+ * workflow's plus `id-token: write`, and each audience as `<NAME>_AUDIENCE`.
  */
 
-import { notifyVariables, opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { notifyVariables, opWaveGroupOf, opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
 import {
   assertEnvironment,
@@ -38,8 +45,9 @@ import {
   dirnameOf,
   environmentDoc,
   GITHUB_JOB_TOKEN,
-  GITHUB_RUNNER,
+  githubRunsOn,
   githubSecretEnv,
+  idTokenAudienceEnv,
   nonEmpty,
   pushBranches,
   setupStepDoc,
@@ -66,27 +74,38 @@ export function buildGithubOpWavesDoc(
   for (const wave of spec.waves) {
     assertSetupSteps(`${spec.name}/${wave.name}`, wave.setup ?? []);
     if (wave.environment) assertEnvironment(`${spec.name}/${wave.name}`, wave.environment);
+    for (const group of wave.jobs ?? []) {
+      assertSetupSteps(`${spec.name}/${wave.name}/${group.name}`, group.setup ?? []);
+      if (group.environment) assertEnvironment(`${spec.name}/${wave.name}/${group.name}`, group.environment);
+    }
   }
+  const permissions = { contents: "write", ...(byReview ? { "pull-requests": "read" } : {}) };
 
   const jobsDoc: Record<string, unknown> = {};
   for (const job of jobs) {
     const wave = spec.waves[job.wave - 1]!;
+    // #3914: a job group's job runs with the group's settings over the wave's.
+    const group = opWaveGroupOf(spec, job);
     const steps: Array<Record<string, unknown>> = [checkoutStep(true)];
     if (job.kind === "share") {
       steps.push(downloadArtifactStep(`Download wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), dirnameOf(job.record!)));
     }
-    steps.push(...(wave.setup ?? []).map(setupStepDoc), ...runSteps(options.beforeScript ?? []));
-    steps.push({ name: describeJob(job.kind, job.wave, wave.name, job.share), run: job.command.join(" ") });
+    steps.push(...[...(wave.setup ?? []), ...(group?.setup ?? [])].map(setupStepDoc), ...runSteps(options.beforeScript ?? []));
+    steps.push({ name: describeJob(job.kind, job.wave, wave.name, job.share, job.group), run: job.command.join(" ") });
     steps.push(...runSteps(options.extraScript ?? []));
     if (job.kind === "decide") {
       steps.push(keepRecordStep(`Keep wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), job.record!));
     }
+    const environment = group?.environment ?? wave.environment;
+    const idTokens = group?.idTokens ?? wave.idTokens;
     jobsDoc[job.jobName] = {
-      "runs-on": GITHUB_RUNNER,
+      "runs-on": githubRunsOn(group?.runner ?? wave.runner ?? spec.runner),
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       container: image,
-      ...(wave.environment ? { environment: environmentDoc(wave.environment) } : {}),
-      ...nonEmpty("env", wave.variables),
+      ...(environment ? { environment: environmentDoc(environment) } : {}),
+      // #3914: a job's own permissions replace the workflow's, so they repeat them.
+      ...(idTokens ? { permissions: { ...permissions, "id-token": "write" } } : {}),
+      ...nonEmpty("env", group || idTokens ? { ...wave.variables, ...group?.variables, ...idTokenAudienceEnv(idTokens) } : wave.variables),
       steps,
     };
   }
@@ -98,7 +117,7 @@ export function buildGithubOpWavesDoc(
     on: { push: { branches: pushBranches(spec.branches) }, workflow_dispatch: {} },
     ...nonEmpty("env", env),
     concurrency: concurrency(spec.name),
-    permissions: { contents: "write", ...(byReview ? { "pull-requests": "read" } : {}) },
+    permissions,
     jobsDoc,
   };
   return {
@@ -123,7 +142,7 @@ function buildResumeDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): Git
     concurrency: concurrency(`${spec.name}-resume`, true),
     // contents: read fetches chant/lifecycle; actions: write re-runs a waiting run.
     permissions: { contents: "read", actions: "write" },
-    jobsDoc: { resume: { "runs-on": GITHUB_RUNNER, container: options.image ?? OP_WAVES_IMAGE, steps } },
+    jobsDoc: { resume: { "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps } },
   };
 }
 
@@ -138,12 +157,13 @@ function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): Gith
     concurrency: concurrency(spec.name + "-plans-${{ github.event.number }}", true),
     // contents: write pushes the record to chant/lifecycle.
     permissions: { contents: "write" },
-    jobsDoc: { "record-plans": { "runs-on": GITHUB_RUNNER, container: options.image ?? OP_WAVES_IMAGE, steps } },
+    jobsDoc: { "record-plans": { "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps } },
   };
 }
 
-function describeJob(kind: "wave" | "decide" | "share", wave: number, name: string, share?: number): string {
+function describeJob(kind: "wave" | "decide" | "share", wave: number, name: string, share?: number, group?: string): string {
   if (kind === "decide") return `Plan wave ${wave} (${name}) and decide its gate`;
+  if (group !== undefined) return `Apply ${share !== undefined ? `share ${share} of ` : ""}job group ${group} of wave ${wave} (${name})`;
   if (kind === "share") return `Apply share ${share} of wave ${wave} (${name})`;
   return `Plan, gate and apply wave ${wave} (${name})`;
 }