@intentius/chant-lexicon-github 0.124.13 → 0.124.15

package/dist/components/ci-jobs.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The GitHub Actions job pieces the three generators share (#3765): the Op
+ * pipeline (`./generate-op-pipeline.ts`), the Op waves pipeline
+ * (`./generate-op-waves-pipeline.ts`) and the component pipeline
+ * (`./generate-pipeline.ts`). The forgejo lexicon builds on the same
+ * documents and applies its dialect. The forge-neutral rules (image default,
+ * branch defaults, tokens, permissions, setup and environment checks) are
+ * core's, in `@intentius/chant/ci-jobs`.
+ */
+import type { OpTrigger } from "@intentius/chant/lexicon";
+/** The artifact actions every generated job uses, at the major the generators have always pinned. */
+export declare const UPLOAD_ARTIFACT = "actions/upload-artifact@v4";
+export declare const DOWNLOAD_ARTIFACT = "actions/download-artifact@v4";
+/** The checkout step; `fullHistory` fetches every commit, for a job that reads the base commit or measures a change with git. */
+export declare function checkoutStep(fullHistory?: boolean): Record<string, unknown>;
+/** One `run:` step per line, so each line is its own step in the log. */
+export declare function runSteps(lines: readonly string[]): Array<Record<string, unknown>>;
+/** A step that downloads `artifact` into `path`. */
+export declare function downloadArtifactStep(name: string, artifact: string, path: string): Record<string, unknown>;
+/**
+ * A step that keeps a record as an artifact whatever the job's outcome, so a
+ * job that stops at a gate (exit 3) still hands its record on, and a re-run
+ * replaces it. Nothing to keep is not an error.
+ */
+export declare function keepRecordStep(name: string, artifact: string, path: string): Record<string, unknown>;
+/** A `concurrency:` mapping: one run at a time per group. */
+export declare function concurrency(group: string, cancelInProgress?: boolean): Record<string, unknown>;
+/** The job token, as a step's `GITHUB_TOKEN`; `gh` reads `GH_TOKEN` too, for a step that writes. */
+export declare function jobTokenEnv(gh?: boolean): Record<string, string>;
+/**
+ * A trigger's `on:` mapping (#2084): `cron` runs on its schedule and by hand,
+ * `pull_request` on pull requests into its branches (every branch when it
+ * names none; no `workflow_dispatch`, since a PR event needs no manual
+ * escape hatch), `push` on pushes to its branches (core's default when it
+ * names none).
+ */
+export declare function onTrigger(trigger: OpTrigger): Record<string, unknown>;
+/**
+ * A workflow document before emission. Every generator's document is one of
+ * these; each leaves out the sections it has no use for.
+ */
+export interface GithubWorkflowDoc {
+    /** Comment lines above the document, `#` included: what a dialect could not carry across (#2257). */
+    header?: string[];
+    /** The workflow's `name:`. */
+    name?: string;
+    /** The `on:` trigger mapping. */
+    on: Record<string, unknown>;
+    /** The workflow-level `env:` mapping, emitted when it has an entry. */
+    env?: Record<string, unknown>;
+    /** The workflow's `defaults:`. */
+    defaults?: Record<string, unknown>;
+    /** The `concurrency:` mapping. */
+    concurrency?: Record<string, unknown>;
+    /** The workflow-level `permissions:` mapping, emitted when it has an entry. */
+    permissions?: Record<string, unknown>;
+    /** The `jobs:` mapping. */
+    jobsDoc: Record<string, unknown>;
+}
+/** Emit a workflow document as YAML, its sections in GitHub's customary order. */
+export declare function emitWorkflowYAML(doc: GithubWorkflowDoc): string;
+//# sourceMappingURL=ci-jobs.d.ts.map

package/dist/components/ci-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-jobs.d.ts","sourceRoot":"","sources":["../../src/components/ci-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1D,qGAAqG;AACrG,eAAO,MAAM,eAAe,+BAA+B,CAAC;AAC5D,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAEhE,iIAAiI;AACjI,wBAAgB,YAAY,CAAC,WAAW,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEjF;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1G;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOpG;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5F;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,EAAE,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASrE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAW/D"}

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

@@ -69,8 +69,10 @@
  * trigger, the gate-notice job beside it — job-level `env:` does not reach
  * that job either, same as `environment:` above does not).
  */
-import type { ComponentPipelineOptions as GenerateGithubOpOptions, OpEnvironment, OpPipelineJob, OpPipelineResult as GenerateGithubOpResult, OpSetupStep, OpTrigger, ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { assertEnvironment, assertSetupSteps, mergePermissions } from "@intentius/chant/ci-jobs";
+import type { ComponentPipelineOptions as GenerateGithubOpOptions, OpPipelineJob, OpPipelineResult as GenerateGithubOpResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
+export { assertEnvironment, assertSetupSteps, mergePermissions };
 /**
  * The structured pipeline document behind one generated file, before YAML
  * emission — exposed so a GitHub-Actions dialect (the forgejo lexicon, #969)
@@ -129,50 +131,6 @@ export interface GithubOpPipelineFile {
     name: string;
     doc: GithubOpPipelineDoc;
 }
-/**
- * Validate a spec's `setup` list (#2242). A `run` entry needs a non-empty
- * line and nothing else. A `uses` entry has to be a pinned
- * `owner/repo[/subpath]@ref`: no bare `owner/repo`, since an unpinned action
- * resolves to its default branch, and no ref in {@link DEFAULT_BRANCH_REFS}
- * for the same reason spelled out loud. Local (`./path`) and container
- * (`docker://`) refs are refused too — they are legal GitHub Actions, but the
- * generator emits a workflow into a repository it has never seen, so it
- * cannot know a local path resolves there.
- */
-export declare function assertSetupSteps(name: string, setup: OpSetupStep[]): void;
-/**
- * Validate a spec's `environment` (#2257). GitHub creates an environment it
- * has never seen on first use rather than failing the run, and an environment
- * created that way carries no protection rules at all — so a job can name one
- * and read as gated while being gated by nothing. Neither this generator nor
- * GitHub can tell those apart at build time (the environment and its
- * reviewers are repository configuration, not workflow content), which is why
- * what is refused here is only the shape that could never bind: a name that
- * is blank, and a `url` that is neither absolute nor an expression the forge
- * resolves. The rest is the README's job to say out loud.
- */
-export declare function assertEnvironment(name: string, environment: OpEnvironment): void;
-/**
- * Merge a spec's additive `permissions` over the finding-mode's own set
- * (#2242), refusing by name anything that is not strictly additive:
- *
- *  - a blanket `write-all`/`read-all`, in either the key or the value
- *    position, which is the exact thing {@link permissionsForMode} exists to
- *    avoid;
- *  - a scope GitHub does not define ({@link GITHUB_TOKEN_SCOPES}), because
- *    GitHub ignores the key and the run silently gets nothing;
- *  - a scope the mode already grants, at any value — additive means additive,
- *    so this can neither downgrade `contents: write` to read nor restate it.
- *    A mode whose set is wrong is fixed by changing the mode, where the
- *    scope and the behavior that spends it stay together;
- *  - `pull-requests: write` on a trigger with no pull request. Pull-request
- *    access is what the finding-modes own: `pull-request` grants it together
- *    with the `contents: write` needed to push the branch first, and
- *    `comment` grants it on the one trigger that carries a pull request to
- *    comment on. Adding it beside a mode that posts nothing, on a cron or
- *    push run, grants write access no step in the generated job can spend.
- */
-export declare function mergePermissions(name: string, base: Record<string, "read" | "write">, additive: Record<string, "read" | "write">, trigger: OpTrigger): Record<string, "read" | "write">;
 /**
  * Build one `GithubOpPipelineDoc` per scheduled Op: its trigger, its `setup`
  * steps, least-privilege `permissions:` for its finding-mode plus whatever

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAKH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EACnD,aAAa,EAEb,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,EACX,SAAS,EAET,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAgVD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CA8BzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,GAAG,IAAI,CAwBhF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAC1C,OAAO,EAAE,SAAS,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAqClC;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CAiG1D;AAwCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAGH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAOhB,gBAAgB,EAIjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAG1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAIhE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAuOD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CA8F1D;AAwCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAMnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}

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,EAIL,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAOD,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,CAkEpI;AA4CD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAKjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAqMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+KnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAU/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAMjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAsKD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "ac146d6030ea7fc4152c7f17bfa7ceee1190e581e57838415efdc9f41860efee",
+    "manifest.json": "b8a0f2d2359a9a92f639124f22b9219da0da2625af176de03ea56331cab26215",
     "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": "51cd66e7c237243e7153d158f2b1c4ee2205d325ed12c270512dcbe6c61057fd"
+  "composite": "1d135e6813c9e6f68698812e294083407f5536ab1d083fe316c10df01e3dca29"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.124.13",
+  "version": "0.124.15",
   "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.13"
+    "@intentius/chant": "^0.124.15"
   }
 }

package/src/components/ci-jobs.ts

@@ -0,0 +1,112 @@
+/**
+ * The GitHub Actions job pieces the three generators share (#3765): the Op
+ * pipeline (`./generate-op-pipeline.ts`), the Op waves pipeline
+ * (`./generate-op-waves-pipeline.ts`) and the component pipeline
+ * (`./generate-pipeline.ts`). The forgejo lexicon builds on the same
+ * documents and applies its dialect. The forge-neutral rules (image default,
+ * branch defaults, tokens, permissions, setup and environment checks) are
+ * core's, in `@intentius/chant/ci-jobs`.
+ */
+
+import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
+import { GITHUB_JOB_TOKEN, pushBranches } from "@intentius/chant/ci-jobs";
+import type { OpTrigger } from "@intentius/chant/lexicon";
+import { actionRef } from "../action-pins";
+
+/** The artifact actions every generated job uses, at the major the generators have always pinned. */
+export const UPLOAD_ARTIFACT = "actions/upload-artifact@v4";
+export const DOWNLOAD_ARTIFACT = "actions/download-artifact@v4";
+
+/** The checkout step; `fullHistory` fetches every commit, for a job that reads the base commit or measures a change with git. */
+export function checkoutStep(fullHistory = false): Record<string, unknown> {
+  return fullHistory ? { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } } : { uses: actionRef("actions/checkout") };
+}
+
+/** One `run:` step per line, so each line is its own step in the log. */
+export function runSteps(lines: readonly string[]): Array<Record<string, unknown>> {
+  return lines.map((line) => ({ run: line }));
+}
+
+/** A step that downloads `artifact` into `path`. */
+export function downloadArtifactStep(name: string, artifact: string, path: string): Record<string, unknown> {
+  return { name, uses: DOWNLOAD_ARTIFACT, with: { name: artifact, path } };
+}
+
+/**
+ * A step that keeps a record as an artifact whatever the job's outcome, so a
+ * job that stops at a gate (exit 3) still hands its record on, and a re-run
+ * replaces it. Nothing to keep is not an error.
+ */
+export function keepRecordStep(name: string, artifact: string, path: string): Record<string, unknown> {
+  return {
+    name,
+    if: "always()",
+    uses: UPLOAD_ARTIFACT,
+    with: { name: artifact, path, "if-no-files-found": "ignore", "include-hidden-files": true, overwrite: true },
+  };
+}
+
+/** A `concurrency:` mapping: one run at a time per group. */
+export function concurrency(group: string, cancelInProgress = false): Record<string, unknown> {
+  return { group, "cancel-in-progress": cancelInProgress };
+}
+
+/** The job token, as a step's `GITHUB_TOKEN`; `gh` reads `GH_TOKEN` too, for a step that writes. */
+export function jobTokenEnv(gh = false): Record<string, string> {
+  return gh ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN, GH_TOKEN: GITHUB_JOB_TOKEN } : { GITHUB_TOKEN: GITHUB_JOB_TOKEN };
+}
+
+/**
+ * A trigger's `on:` mapping (#2084): `cron` runs on its schedule and by hand,
+ * `pull_request` on pull requests into its branches (every branch when it
+ * names none; no `workflow_dispatch`, since a PR event needs no manual
+ * escape hatch), `push` on pushes to its branches (core's default when it
+ * names none).
+ */
+export function onTrigger(trigger: OpTrigger): Record<string, unknown> {
+  switch (trigger.kind) {
+    case "cron":
+      return { schedule: [{ cron: trigger.schedule }], workflow_dispatch: {} };
+    case "pull_request":
+      return { pull_request: trigger.branches && trigger.branches.length > 0 ? { branches: trigger.branches } : {} };
+    case "push":
+      return { push: { branches: pushBranches(trigger.branches) } };
+  }
+}
+
+/**
+ * A workflow document before emission. Every generator's document is one of
+ * these; each leaves out the sections it has no use for.
+ */
+export interface GithubWorkflowDoc {
+  /** Comment lines above the document, `#` included: what a dialect could not carry across (#2257). */
+  header?: string[];
+  /** The workflow's `name:`. */
+  name?: string;
+  /** The `on:` trigger mapping. */
+  on: Record<string, unknown>;
+  /** The workflow-level `env:` mapping, emitted when it has an entry. */
+  env?: Record<string, unknown>;
+  /** The workflow's `defaults:`. */
+  defaults?: Record<string, unknown>;
+  /** The `concurrency:` mapping. */
+  concurrency?: Record<string, unknown>;
+  /** The workflow-level `permissions:` mapping, emitted when it has an entry. */
+  permissions?: Record<string, unknown>;
+  /** The `jobs:` mapping. */
+  jobsDoc: Record<string, unknown>;
+}
+
+/** Emit a workflow document as YAML, its sections in GitHub's customary order. */
+export function emitWorkflowYAML(doc: GithubWorkflowDoc): string {
+  const sections: string[] = [];
+  if (doc.header && doc.header.length > 0) sections.push(doc.header.join("\n"));
+  if (doc.name) sections.push("name: " + emitYAML(doc.name, 0));
+  sections.push(emitYAMLEntry("on", doc.on));
+  if (doc.env && Object.keys(doc.env).length > 0) sections.push(emitYAMLEntry("env", doc.env));
+  if (doc.defaults) sections.push(emitYAMLEntry("defaults", doc.defaults));
+  if (doc.concurrency) sections.push(emitYAMLEntry("concurrency", doc.concurrency));
+  if (doc.permissions && Object.keys(doc.permissions).length > 0) sections.push(emitYAMLEntry("permissions", doc.permissions));
+  sections.push(emitYAMLEntry("jobs", doc.jobsDoc));
+  return sections.join("\n\n") + "\n";
+}

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

@@ -779,3 +779,12 @@ describe("generateGithubOpPipeline: per-Op variables on the job (#2290)", () =>
     ).toBe(before);
   });
 });
+
+describe("an empty branch list means the default, as on GitLab (#3765)", () => {
+  test("push with branches: [] filters on main, and pull_request with branches: [] runs on every pull request", () => {
+    const push = parseYAML(generateGithubOpPipeline([{ name: "apply", trigger: { kind: "push", branches: [] } }]).files[0]!.yaml);
+    expect(push.on).toEqual({ push: { branches: ["main"] } });
+    const pr = parseYAML(generateGithubOpPipeline([{ name: "plan", trigger: { kind: "pull_request", branches: [] } }]).files[0]!.yaml);
+    expect(pr.on).toEqual({ pull_request: {} });
+  });
+});

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

@@ -71,23 +71,38 @@
  */
 
 import { readFileSync } from "node:fs";
-import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
+import {
+  assertEnvironment,
+  assertSetupSteps,
+  CI_IMAGE,
+  ciJobName,
+  environmentDoc,
+  fillCommand,
+  GITHUB_JOB_TOKEN,
+  GITHUB_RUNNER,
+  mergePermissions,
+  nonEmpty,
+  permissionsFor,
+  setupStepDoc,
+} from "@intentius/chant/ci-jobs";
 import { memberPathFilter, resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGithubOpOptions,
-  OpEnvironment,
   OpFindingMode,
   OpPipelineJob,
   OpPipelineResult as GenerateGithubOpResult,
-  OpSetupStep,
   OpTrigger,
   PipelineMember,
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
-import { actionRef } from "../action-pins";
+import { checkoutStep, concurrency, emitWorkflowYAML, jobTokenEnv, onTrigger, runSteps } from "./ci-jobs";
 
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 
+// The setup, environment and permission checks are shared with the Op waves
+// generator and the forgejo lexicon (#3765); they stay importable from here.
+export { assertEnvironment, assertSetupSteps, mergePermissions };
+
 /**
  * The structured pipeline document behind one generated file, before YAML
  * emission — exposed so a GitHub-Actions dialect (the forgejo lexicon, #969)
@@ -148,72 +163,6 @@ export interface GithubOpPipelineFile {
   doc: GithubOpPipelineDoc;
 }
 
-/** GitHub Actions job ids must match `[a-zA-Z_][a-zA-Z0-9_-]*`; 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";
-
-/**
- * Default branch assumed for a `push` trigger with no `branches` override
- * (#2084). There is no generator constant for a downstream project's actual
- * default branch — this operates on a `ScheduledOpSpec`, not a git checkout
- * — so "main" is the documented default; set `trigger.branches` explicitly
- * for a project whose default branch is something else (e.g. "master").
- */
-const DEFAULT_PUSH_BRANCH = "main";
-
-/** This trigger's `on:` mapping (#2084): cron unchanged, `pull_request`/`push` new. */
-function onFor(trigger: OpTrigger): Record<string, unknown> {
-  switch (trigger.kind) {
-    case "cron":
-      return { schedule: [{ cron: trigger.schedule }], workflow_dispatch: {} };
-    case "pull_request":
-      // No `workflow_dispatch`: a PR trigger needs no manual-dispatch escape
-      // hatch (revisit in review if that's wrong).
-      return { pull_request: trigger.branches ? { branches: trigger.branches } : {} };
-    case "push":
-      return { push: { branches: trigger.branches ?? [DEFAULT_PUSH_BRANCH] } };
-  }
-}
-
-/**
- * Least-privilege `permissions:` for a scheduled Op's finding-mode and
- * trigger. `report` needs no write access; `issue` needs only `issues:
- * write`; `pull-request` (and `merge-request`, generated the same way when a
- * GitLab-authored spec is targeted at github) needs `contents: write` to
- * push the reconcile branch plus `pull-requests: write` to open the PR. A
- * `pull_request` trigger reports its finding as a comment on the triggering
- * PR itself (#2084): any mode but `report` posts something to act on a
- * finding, so on that trigger every such mode also gets `pull-requests:
- * write` for the comment, whether or not its own scope already included it.
- * `comment` is the mode that actually spends that grant (#2231), and it
- * changes nothing in the repository, so its whole scope is `{ contents: read,
- * pull-requests: write }`.
- */
-function permissionsForMode(mode: OpFindingMode): Record<string, "read" | "write"> {
-  switch (mode) {
-    case "issue":
-      return { contents: "read", issues: "write" };
-    case "comment":
-      return { contents: "read", "pull-requests": "write" };
-    case "pull-request":
-    case "merge-request":
-      return { contents: "write", "pull-requests": "write" };
-    case "report":
-      return { contents: "read" };
-  }
-}
-
-function permissionsFor(mode: OpFindingMode, trigger: OpTrigger): Record<string, "read" | "write"> {
-  const base = permissionsForMode(mode);
-  if (trigger.kind === "pull_request" && mode !== "report") {
-    return { ...base, "pull-requests": "write" };
-  }
-  return base;
-}
-
 // ── The gated apply (#2243) ─────────────────────────────────────────────────
 
 /**
@@ -330,7 +279,8 @@ function chantVersion(): string {
  * `@intentius/chant/pr-forge` clients, so it posts on GitHub, GitHub
  * Enterprise Server and Forgejo alike. `forgeTargetFromEnv` reads the forge,
  * the REST base, the repository, the commit and the token off the job's
- * environment (`CHANT_FORGEJO_TOKEN`, then `GH_TOKEN`, then `GITHUB_TOKEN`),
+ * environment (`FORGE_TOKEN_ORDER`: `CHANT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` on
+ * GitHub; `CHANT_FORGEJO_TOKEN` first on Forgejo), the order `reconcilePr` reads too (#3807),
  * and `pullRequestFor` is the commit-to-pull-request lookup each forge spells
  * its own way (`commits/{sha}/pulls` on GitHub, `commits/{sha}/pull` on
  * Forgejo). A commit with no pull request, a direct push, gets a tracking
@@ -408,14 +358,14 @@ function gateNoticeJob(applyJobName: string, image: string): Record<string, unkn
   return {
     needs: applyJobName,
     if: `needs.${applyJobName}.outputs.gated == 'true'`,
-    "runs-on": "ubuntu-latest",
+    "runs-on": GITHUB_RUNNER,
     container: image,
     permissions: { contents: "read", issues: "write", "pull-requests": "write" },
     steps: [
       {
         name: "Report the pending gate",
         env: {
-          GITHUB_TOKEN: "${{ github.token }}",
+          GITHUB_TOKEN: GITHUB_JOB_TOKEN,
           CHANT_OP: output("op"),
           CHANT_GATE: output("gate"),
           CHANT_APPROVE: output("approve"),
@@ -442,216 +392,6 @@ function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: O
   );
 }
 
-/**
- * Every scope `GITHUB_TOKEN` accepts in a workflow's `permissions:` mapping,
- * kebab-cased as GitHub spells them. An additive scope outside this set is
- * refused by name rather than emitted: GitHub ignores an unknown key, so
- * `id_token` or `idToken` would generate a workflow that looks like it grants
- * OIDC and hands the run no token at all.
- */
-const GITHUB_TOKEN_SCOPES = new Set([
-  "actions",
-  "attestations",
-  "checks",
-  "contents",
-  "deployments",
-  "discussions",
-  "id-token",
-  "issues",
-  "models",
-  "packages",
-  "pages",
-  "pull-requests",
-  "repository-projects",
-  "security-events",
-  "statuses",
-]);
-
-/**
- * Refs that name an action repository's own default branch. A generated
- * workflow is committed once and then re-run unattended, often over a cloud
- * role, so "whatever was pushed to that repo last" is not a version — the
- * code that assumes the role can change between the run somebody reviewed and
- * the next one. A release channel the action's author cuts deliberately (`v6`,
- * `v6.2.4`, `stable`) or a commit sha is a version, and both pass: this repo's
- * own workflows pin `actions/checkout@v6` and `dtolnay/rust-toolchain@stable`
- * and name no default branch anywhere.
- */
-const DEFAULT_BRANCH_REFS = new Set(["main", "master", "head", "default"]);
-
-/** `owner/repo` or `owner/repo/subpath`, then `@ref`. */
-const USES_PATTERN = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)((?:\/[A-Za-z0-9_.-]+)*)@([^\s@]+)$/;
-
-/**
- * Validate a spec's `setup` list (#2242). A `run` entry needs a non-empty
- * line and nothing else. A `uses` entry has to be a pinned
- * `owner/repo[/subpath]@ref`: no bare `owner/repo`, since an unpinned action
- * resolves to its default branch, and no ref in {@link DEFAULT_BRANCH_REFS}
- * for the same reason spelled out loud. Local (`./path`) and container
- * (`docker://`) refs are refused too — they are legal GitHub Actions, but the
- * generator emits a workflow into a repository it has never seen, so it
- * cannot know a local path resolves there.
- */
-export function assertSetupSteps(name: string, setup: OpSetupStep[]): void {
-  setup.forEach((step, index) => {
-    const where = `Scheduled Op "${name}" setup step ${index + 1}`;
-    if ("uses" in step) {
-      const ref = step.uses.trim();
-      const match = USES_PATTERN.exec(ref);
-      if (!match) {
-        throw new Error(
-          `${where} has \`uses: "${step.uses}"\`, which is not a pinned action reference. ` +
-            `Write it as owner/repo@ref (optionally owner/repo/subpath@ref), e.g. ` +
-            `"aws-actions/configure-aws-credentials@v6". A local "./path" or "docker://" ref is not ` +
-            `accepted here: this generator emits a workflow into a repository it cannot inspect, so it ` +
-            `has no way to tell whether such a ref resolves there.`,
-        );
-      }
-      const gitRef = match[4];
-      if (DEFAULT_BRANCH_REFS.has(gitRef.toLowerCase())) {
-        throw new Error(
-          `${where} pins \`uses: "${step.uses}"\` to "${gitRef}", the action repository's own default ` +
-            `branch, which names whatever was pushed there last rather than a version. A generated ` +
-            `workflow is committed once and re-run unattended, often over a cloud role, so pin a release ` +
-            `tag or a commit sha instead (e.g. "${match[1]}/${match[2]}@v1" or "@<40-char sha>").`,
-        );
-      }
-      return;
-    }
-    if (step.run.trim() === "") {
-      throw new Error(`${where} has an empty \`run\` line. Give it a command, or drop the entry.`);
-    }
-  });
-}
-
-/**
- * Validate a spec's `environment` (#2257). GitHub creates an environment it
- * has never seen on first use rather than failing the run, and an environment
- * created that way carries no protection rules at all — so a job can name one
- * and read as gated while being gated by nothing. Neither this generator nor
- * GitHub can tell those apart at build time (the environment and its
- * reviewers are repository configuration, not workflow content), which is why
- * what is refused here is only the shape that could never bind: a name that
- * is blank, and a `url` that is neither absolute nor an expression the forge
- * resolves. The rest is the README's job to say out loud.
- */
-export function assertEnvironment(name: string, environment: OpEnvironment): void {
-  const where = `Scheduled Op "${name}" environment`;
-  if (environment.name.trim() === "") {
-    throw new Error(
-      `${where} has an empty \`name\`. An environment is named repository configuration — the ` +
-        `protection rules and reviewers live on the environment, not in this workflow — so there is ` +
-        `nothing for a blank name to resolve to. 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 \${{ }} expression. GitHub renders this value as the deployment's own link, ` +
-        `so a relative path becomes a dead link on the environment page rather than an error anywhere. ` +
-        `Write the full URL, or an expression the run resolves to one.`,
-    );
-  }
-}
-
-/**
- * Merge a spec's additive `permissions` over the finding-mode's own set
- * (#2242), refusing by name anything that is not strictly additive:
- *
- *  - a blanket `write-all`/`read-all`, in either the key or the value
- *    position, which is the exact thing {@link permissionsForMode} exists to
- *    avoid;
- *  - a scope GitHub does not define ({@link GITHUB_TOKEN_SCOPES}), because
- *    GitHub ignores the key and the run silently gets nothing;
- *  - a scope the mode already grants, at any value — additive means additive,
- *    so this can neither downgrade `contents: write` to read nor restate it.
- *    A mode whose set is wrong is fixed by changing the mode, where the
- *    scope and the behavior that spends it stay together;
- *  - `pull-requests: write` on a trigger with no pull request. Pull-request
- *    access is what the finding-modes own: `pull-request` grants it together
- *    with the `contents: write` needed to push the branch first, and
- *    `comment` grants it on the one trigger that carries a pull request to
- *    comment on. Adding it beside a mode that posts nothing, on a cron or
- *    push run, grants write access no step in the generated job can spend.
- */
-export function mergePermissions(
-  name: string,
-  base: Record<string, "read" | "write">,
-  additive: Record<string, "read" | "write">,
-  trigger: OpTrigger,
-): Record<string, "read" | "write"> {
-  const merged: Record<string, "read" | "write"> = { ...base };
-  for (const [rawScope, value] of Object.entries(additive)) {
-    const scope = rawScope.trim();
-    const where = `Scheduled Op "${name}" adds permission "${scope}: ${value}"`;
-    if (scope === "write-all" || scope === "read-all" || String(value).endsWith("-all")) {
-      throw new Error(
-        `${where}, a blanket grant. \`permissions\` on a scheduled Op is additive over the ` +
-          `least-privilege set its finding-mode needs, one named scope at a time. Name the scopes the ` +
-          `job actually spends (e.g. { "id-token": "write" }).`,
-      );
-    }
-    if (!GITHUB_TOKEN_SCOPES.has(scope)) {
-      throw new Error(
-        `${where}, which is not a GITHUB_TOKEN permission scope. GitHub ignores an unrecognized key, so ` +
-          `this would emit a workflow that reads as granted and hands the run nothing. Known scopes: ` +
-          `${[...GITHUB_TOKEN_SCOPES].sort().join(", ")}.`,
-      );
-    }
-    if (scope in base) {
-      throw new Error(
-        `${where}, but its finding-mode already grants "${scope}: ${base[scope]}". These permissions are ` +
-          `additive only — they never replace, widen or downgrade a scope the mode computed. Change the ` +
-          `Op's findingMode if that set is wrong, and add only scopes no mode grants (e.g. "id-token").`,
-      );
-    }
-    if (scope === "pull-requests" && trigger.kind !== "pull_request") {
-      throw new Error(
-        `${where}, but this Op's trigger is "${trigger.kind}", which carries no pull request. Pull-request ` +
-          `write access belongs to a finding-mode: "pull-request" grants it with the contents: write its ` +
-          `branch push needs, and "comment" grants it on the pull_request trigger. Set findingMode instead ` +
-          `of adding the scope here.`,
-      );
-    }
-    merged[scope] = value;
-  }
-  return merged;
-}
-
-/**
- * Emit a spec's environment as the job's `environment:` mapping. Always the
- * mapping form, never the `environment: name` string shorthand, so adding a
- * `url` later is a new key rather than a reshaped value.
- */
-function environmentDoc(environment: OpEnvironment): Record<string, unknown> {
-  return {
-    name: environment.name,
-    ...(environment.url === undefined ? {} : { url: environment.url }),
-  };
-}
-
-/** Emit one setup entry as a GitHub Actions step. */
-function setupStepDoc(step: OpSetupStep): Record<string, unknown> {
-  if ("uses" in step) {
-    return {
-      uses: step.uses,
-      ...(step.with && Object.keys(step.with).length > 0 ? { with: step.with } : {}),
-      ...(step.env && Object.keys(step.env).length > 0 ? { env: step.env } : {}),
-    };
-  }
-  return {
-    run: step.run,
-    ...(step.env && Object.keys(step.env).length > 0 ? { env: step.env } : {}),
-  };
-}
-
 /**
  * Build one `GithubOpPipelineDoc` per scheduled Op: its trigger, its `setup`
  * steps, least-privilege `permissions:` for its finding-mode plus whatever
@@ -668,7 +408,7 @@ export function buildGithubOpPipelineDocs(
   ops: ScheduledOpSpec[],
   options: GenerateGithubOpOptions = {},
 ): { files: GithubOpPipelineFile[]; jobs: OpPipelineJob[] } {
-  const image = options.image ?? DEFAULT_IMAGE;
+  const image = options.image ?? CI_IMAGE;
   const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
   const beforeScript = options.beforeScript ?? [];
   const extraScript = options.extraScript ?? [];
@@ -680,15 +420,14 @@ export function buildGithubOpPipelineDocs(
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
-    const jobName = toJobName(spec.name);
+    const jobName = ciJobName(spec.name);
     jobs.push({ jobName, op: spec.name, trigger, findingMode });
 
-    const runParts = runCommand.map((part) => part.replace("{name}", spec.name));
+    const runParts = fillCommand(runCommand, spec.name);
 
     // A live-resolution read (rate limits) always benefits from a token;
     // creating an issue/PR additionally needs `gh` CLI's own token variable.
-    const stepEnv: Record<string, string> = { GITHUB_TOKEN: "${{ github.token }}" };
-    if (findingMode !== "report") stepEnv.GH_TOKEN = "${{ github.token }}";
+    const stepEnv = jobTokenEnv(findingMode !== "report");
 
     const setup = spec.setup ?? [];
     assertSetupSteps(spec.name, setup);
@@ -703,23 +442,21 @@ export function buildGithubOpPipelineDocs(
       ? [...runParts, ...GATED_EXIT_FLAG, "--json"].join(" ")
       : runParts.join(" ");
 
-    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
-    for (const step of setup) steps.push(setupStepDoc(step));
-    for (const line of beforeScript) steps.push({ run: line });
+    const steps: Array<Record<string, unknown>> = [checkoutStep(), ...setup.map(setupStepDoc), ...runSteps(beforeScript)];
     steps.push(
       gated
         ? gatedRunStep(RUN_STEP_ID, spec.name, invocation, stepEnv)
         : { run: invocation, env: stepEnv },
     );
-    for (const line of extraScript) steps.push({ run: line });
+    steps.push(...runSteps(extraScript));
 
     const doc: GithubOpPipelineDoc = {
       name: spec.name,
-      on: onFor(trigger),
-      ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
+      on: onTrigger(trigger),
+      ...nonEmpty("env", options.variables),
       // One run at a time per Op — a slow audit must not overlap its own next
       // scheduled trigger.
-      concurrency: { group: jobName, "cancel-in-progress": false },
+      concurrency: concurrency(jobName),
       permissions: mergePermissions(
         spec.name,
         permissionsFor(findingMode, trigger),
@@ -728,13 +465,13 @@ export function buildGithubOpPipelineDocs(
       ),
       jobsDoc: {
         [jobName]: {
-          "runs-on": "ubuntu-latest",
+          "runs-on": GITHUB_RUNNER,
           container: image,
           // Per-Op credentials (#2290): job-level `env:`, one level more
           // specific than `options.variables`'s workflow-level `env:` above,
           // and never on the notice job beside it — same reason `environment:`
           // isn't either, it's this Op's own job alone.
-          ...(spec.variables && Object.keys(spec.variables).length > 0 ? { env: spec.variables } : {}),
+          ...nonEmpty("env", spec.variables),
           // On this Op's own job and never on the notice job beside it: the
           // notice exists to say a chant gate is pending, and putting it
           // behind the same reviewer would hold the message back until
@@ -810,20 +547,11 @@ function scopeOpFileToMember(file: GithubOpPipelineFile, member: PipelineMember)
  * transforms the doc first (and drops `permissions`, which it ignores).
  */
 export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
-  const sections: string[] = [];
-  // A dialect's note about what it could not carry (#2257), when there is
-  // one. Absent on github, so an unannotated document is emitted exactly as
-  // it was before the field existed.
-  if (doc.header && doc.header.length > 0) sections.push(doc.header.join("\n"));
-  if (doc.name) sections.push("name: " + emitYAML(doc.name, 0));
-  sections.push(emitYAMLEntry("on", doc.on));
-  if (doc.env && Object.keys(doc.env).length > 0) sections.push(emitYAMLEntry("env", doc.env));
-  sections.push(emitYAMLEntry("concurrency", doc.concurrency));
-  if (Object.keys(doc.permissions).length > 0) sections.push(emitYAMLEntry("permissions", doc.permissions));
   // The gated-apply notice job rides in `jobs:` beside the Op's own job; it
   // is carried separately on the doc so a dialect transforms it on its own.
-  sections.push(emitYAMLEntry("jobs", { ...doc.jobsDoc, ...(doc.gatedNoticeDoc ?? {}) }));
-  return sections.join("\n\n") + "\n";
+  // A dialect's `header` note (#2257) is absent on github.
+  const { gatedNoticeDoc, ...workflow } = doc;
+  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}) } });
 }
 
 /**

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

@@ -31,27 +31,30 @@
 
 import { notifyVariables, opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
-import { actionRef } from "../action-pins";
 import {
   assertEnvironment,
   assertSetupSteps,
-  emitOpPipelineYAML,
-  type GithubOpPipelineDoc,
-} from "./generate-op-pipeline";
+  CI_IMAGE,
+  dirnameOf,
+  environmentDoc,
+  GITHUB_JOB_TOKEN,
+  GITHUB_RUNNER,
+  githubSecretEnv,
+  nonEmpty,
+  pushBranches,
+  setupStepDoc,
+} from "@intentius/chant/ci-jobs";
+import { checkoutStep, concurrency, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs";
+import { emitOpPipelineYAML, type GithubOpPipelineDoc } from "./generate-op-pipeline";
 
 /** The default image: it carries git, which the runner needs to read the base commit. */
-export const OP_WAVES_IMAGE = "node:22";
+export const OP_WAVES_IMAGE = CI_IMAGE;
 
 /** The artifact a wide wave's deciding job hands its share jobs. */
 export function opWaveRecordArtifact(spec: Pick<OpWavesSpec, "name">, wave: number): string {
   return `${spec.name}-wave-${wave}-decision`;
 }
 
-function dirOf(path: string): string {
-  const i = path.lastIndexOf("/");
-  return i < 0 ? "." : path.slice(0, i);
-}
-
 /** The workflow document, before emission, and the jobs it holds. */
 export function buildGithubOpWavesDoc(
   spec: OpWavesSpec,
@@ -68,51 +71,33 @@ export function buildGithubOpWavesDoc(
   const jobsDoc: Record<string, unknown> = {};
   for (const job of jobs) {
     const wave = spec.waves[job.wave - 1]!;
-    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } }];
+    const steps: Array<Record<string, unknown>> = [checkoutStep(true)];
     if (job.kind === "share") {
-      steps.push({
-        name: `Download wave ${job.wave}'s decision`,
-        uses: "actions/download-artifact@v4",
-        with: { name: opWaveRecordArtifact(spec, job.wave), path: dirOf(job.record!) },
-      });
+      steps.push(downloadArtifactStep(`Download wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), dirnameOf(job.record!)));
     }
-    for (const step of wave.setup ?? []) steps.push({ ...step });
-    for (const line of options.beforeScript ?? []) steps.push({ run: line });
+    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(" ") });
-    for (const line of options.extraScript ?? []) steps.push({ run: line });
+    steps.push(...runSteps(options.extraScript ?? []));
     if (job.kind === "decide") {
-      steps.push({
-        name: `Keep wave ${job.wave}'s decision`,
-        if: "always()",
-        uses: "actions/upload-artifact@v4",
-        with: {
-          name: opWaveRecordArtifact(spec, job.wave),
-          path: job.record!,
-          "if-no-files-found": "ignore",
-          "include-hidden-files": true,
-          overwrite: true,
-        },
-      });
+      steps.push(keepRecordStep(`Keep wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), job.record!));
     }
     jobsDoc[job.jobName] = {
-      "runs-on": "ubuntu-latest",
+      "runs-on": GITHUB_RUNNER,
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       container: image,
-      ...(wave.environment
-        ? { environment: { name: wave.environment.name, ...(wave.environment.url ? { url: wave.environment.url } : {}) } }
-        : {}),
-      ...(wave.variables && Object.keys(wave.variables).length > 0 ? { env: wave.variables } : {}),
+      ...(wave.environment ? { environment: environmentDoc(wave.environment) } : {}),
+      ...nonEmpty("env", wave.variables),
       steps,
     };
   }
 
   // #3761: the notify variables come from the secrets of the same name.
-  const env = { ...Object.fromEntries(notifyVariables(spec.notify).map((n) => [n, `\${{ secrets.${n} }}`])), ...(options.variables ?? {}) };
+  const env = { ...githubSecretEnv(notifyVariables(spec.notify)), ...(options.variables ?? {}) };
   const doc: GithubOpPipelineDoc = {
     name: spec.name,
-    on: { push: { branches: spec.branches?.length ? spec.branches : ["main"] }, workflow_dispatch: {} },
-    ...(Object.keys(env).length > 0 ? { env } : {}),
-    concurrency: { group: spec.name, "cancel-in-progress": false },
+    on: { push: { branches: pushBranches(spec.branches) }, workflow_dispatch: {} },
+    ...nonEmpty("env", env),
+    concurrency: concurrency(spec.name),
     permissions: { contents: "write", ...(byReview ? { "pull-requests": "read" } : {}) },
     jobsDoc,
   };
@@ -126,37 +111,34 @@ export function buildGithubOpWavesDoc(
 
 /** The scheduled resume workflow (#3683). */
 function buildResumeDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
-  const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
-  for (const line of options.beforeScript ?? []) steps.push({ run: line });
+  const steps: Array<Record<string, unknown>> = [checkoutStep(), ...runSteps(options.beforeScript ?? [])];
   steps.push({
     name: `Resume the waves of ${spec.name} whose approval arrived`,
     run: opWavesResumeCommand(spec).join(" "),
-    env: { GITHUB_TOKEN: "${{ github.token }}" },
+    env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN },
   });
   return {
     name: `${spec.name}-resume`,
     on: { schedule: [{ cron: spec.resume!.schedule }], workflow_dispatch: {} },
-    concurrency: { group: `${spec.name}-resume`, "cancel-in-progress": true },
+    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": "ubuntu-latest", container: options.image ?? OP_WAVES_IMAGE, steps } },
+    jobsDoc: { resume: { "runs-on": GITHUB_RUNNER, container: options.image ?? OP_WAVES_IMAGE, steps } },
   };
 }
 
 /** The pull request workflow a `pr-review` wave needs (#3684): record the digests each head plans. */
 function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
-  const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } }];
-  for (const step of spec.waves[0]?.setup ?? []) steps.push({ ...step });
-  for (const line of options.beforeScript ?? []) steps.push({ run: line });
+  const steps: Array<Record<string, unknown>> = [checkoutStep(true), ...(spec.waves[0]?.setup ?? []).map(setupStepDoc), ...runSteps(options.beforeScript ?? [])];
   steps.push({ name: "Plan every wave at the head and record its digests", run: ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ") });
   return {
     name: `${spec.name}-plans`,
-    on: { pull_request: { branches: spec.branches?.length ? spec.branches : ["main"] } },
-    ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
-    concurrency: { group: spec.name + "-plans-${{ github.event.number }}", "cancel-in-progress": true },
+    on: { pull_request: { branches: pushBranches(spec.branches) } },
+    ...nonEmpty("env", options.variables),
+    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": "ubuntu-latest", container: options.image ?? OP_WAVES_IMAGE, steps } },
+    jobsDoc: { "record-plans": { "runs-on": GITHUB_RUNNER, container: options.image ?? OP_WAVES_IMAGE, steps } },
   };
 }
 

package/src/components/generate-pipeline.ts

@@ -56,11 +56,11 @@
  * touching the component declarations.
  */
 
-import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
 import { resolveComponentGraph, type DriverComponent } 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_IMAGE, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prLoopJobs, prLoopSetup } from "@intentius/chant/components/pr-pipeline";
+import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prLoopJobs, prLoopSetup } from "@intentius/chant/components/pr-pipeline";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -68,7 +68,7 @@ import type {
   ComponentPipelineResult as GenerateGithubResult,
   PipelineMember,
 } from "@intentius/chant/lexicon";
-import { actionRef } from "../action-pins";
+import { checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
 
 export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
 
@@ -134,32 +134,14 @@ function gatedWaveGithubDoc(
   const jobs: GeneratedJob[] = [];
   for (const job of waveJobs) {
     jobs.push({ jobName: job.jobName, component: `wave ${job.wave}`, stage: job.jobName, needs: job.needs });
-    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } }];
+    const steps: Array<Record<string, unknown>> = [checkoutStep(true)];
     if (job.wave > 1) {
-      steps.push({
-        name: `Download the record wave ${job.wave - 1} left`,
-        uses: "actions/download-artifact@v4",
-        with: { name: waveRecordArtifact(job.wave - 1), path: dirnameOf(GATED_WAVE_RECORD) },
-      });
+      steps.push(downloadArtifactStep(`Download the record wave ${job.wave - 1} left`, waveRecordArtifact(job.wave - 1), dirnameOf(GATED_WAVE_RECORD)));
     }
-    for (const line of prLoopSetup(image)) steps.push({ run: line });
-    for (const line of beforeScript) steps.push({ run: line });
-    steps.push({ run: job.command.join(" ") });
-    for (const line of extraScript) steps.push({ run: line });
-    steps.push({
-      name: `Upload the record for wave ${job.wave}`,
-      if: "always()",
-      uses: "actions/upload-artifact@v4",
-      with: {
-        name: waveRecordArtifact(job.wave),
-        path: GATED_WAVE_RECORD,
-        "if-no-files-found": "ignore",
-        "include-hidden-files": true,
-        overwrite: true,
-      },
-    });
+    steps.push(...runSteps(prLoopSetup(image)), ...runSteps(beforeScript), { run: job.command.join(" ") }, ...runSteps(extraScript));
+    steps.push(keepRecordStep(`Upload the record for wave ${job.wave}`, waveRecordArtifact(job.wave), GATED_WAVE_RECORD));
     jobsDoc[job.jobName] = {
-      "runs-on": "ubuntu-latest",
+      "runs-on": GITHUB_RUNNER,
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       container: image,
       steps,
@@ -225,33 +207,33 @@ function prLoopGithubDoc(
     with: { path: recordPath, key: recordKey },
   };
   const steps = (job: typeof plan, name: string): Array<Record<string, unknown>> => [
-    { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } },
-    ...prLoopSetup(image).map((line) => ({ run: line })),
-    ...beforeScript.map((line) => ({ run: line })),
+    checkoutStep(true),
+    ...runSteps(prLoopSetup(image)),
+    ...runSteps(beforeScript),
     ...(job.jobName === "apply" ? [restoreRecord] : []),
     { name, env: job.env, run: job.command },
-    ...extraScript.map((line) => ({ run: line })),
+    ...runSteps(extraScript),
     ...(job.jobName === "apply" ? [saveRecord] : []),
     {
       name: `Keep the ${job.jobName} report`,
       if: "always()",
-      uses: "actions/upload-artifact@v4",
+      uses: UPLOAD_ARTIFACT,
       with: { name: `chant-pr-${job.jobName}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true },
     },
   ];
   const jobsDoc: Record<string, unknown> = {
     plan: {
       if: "github.event_name == 'pull_request'",
-      "runs-on": "ubuntu-latest",
+      "runs-on": GITHUB_RUNNER,
       container: image,
       permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
       steps: steps(plan, "Plan the members this pull request reaches"),
     },
     apply: {
       if: "github.event_name == 'push'",
-      "runs-on": "ubuntu-latest",
+      "runs-on": GITHUB_RUNNER,
       container: image,
-      concurrency: { group: prApplyGroup(env, member?.name), "cancel-in-progress": false },
+      concurrency: concurrency(prApplyGroup(env, member?.name)),
       permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
       steps: steps(apply, "Apply the plan a reviewer approved"),
     },
@@ -271,19 +253,6 @@ function prLoopGithubDoc(
   };
 }
 
-/** The directory part of a relative path, `.` when there is none. */
-function dirnameOf(path: string): string {
-  const i = path.lastIndexOf("/");
-  return i <= 0 ? "." : path.slice(0, i);
-}
-
-/** GitHub Actions job ids must match `[a-zA-Z_][a-zA-Z0-9_-]*`; component names are already kebab-case in every fixture, but normalize defensively (mirrors gitlab's `toJobName`). */
-function toJobName(componentName: string): string {
-  return componentName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
-
-const DEFAULT_IMAGE = "node:22";
-
 /** The file a producer dumps its resolved outputs to, and a dependent seeds from — one per component, matching gitlab's naming so both generators produce interchangeable artifacts. */
 function outputsFile(name: string): string {
   return `${name}.outputs.json`;
@@ -336,7 +305,7 @@ export function buildGithubPipelineDoc(
   options: GenerateGithubOptions = {},
 ): GithubPipelineDoc {
   const env = options.env ?? "production";
-  const image = options.image ?? (options.prLoop || options.gatedWaves ? PR_LOOP_IMAGE : DEFAULT_IMAGE);
+  const image = options.image ?? CI_IMAGE;
   const runCommand = options.runCommand ?? ["chant", "run", "--components", "{name}", "--env", env];
   const beforeScript = options.beforeScript ?? [];
   const extraScript = options.extraScript ?? [];
@@ -390,7 +359,7 @@ export function buildGithubPipelineDoc(
   const jobs: GeneratedJob[] = [];
   const jobNameByComponent = new Map<string, string>();
   for (const wave of waves) {
-    for (const name of wave) jobNameByComponent.set(name, toJobName(name));
+    for (const name of wave) jobNameByComponent.set(name, ciJobName(name));
   }
 
   const jobsDoc: Record<string, unknown> = {};
@@ -407,7 +376,7 @@ export function buildGithubPipelineDoc(
       // Build the run invocation, then append output-threading flags: seed from
       // each dependency's dumped outputs (downloaded as an artifact below), and
       // dump this component's own outputs if a dependent will need them.
-      const runParts = runCommand.map((part) => part.replace("{name}", name));
+      const runParts = fillCommand(runCommand, name);
       for (const dep of component.dependsOn ?? []) runParts.push("--seed-outputs", outputsFile(dep));
       if (dependedUpon.has(name)) runParts.push("--dump-outputs", outputsFile(name));
       if (pinned.has(name)) runParts.push("--digest-file", digestFile(name));
@@ -415,19 +384,9 @@ export function buildGithubPipelineDoc(
       // One step per script line — mirrors gitlab's `script:` array of
       // discrete shell lines, rather than a single multi-line `run:` block, so
       // each line is independently inspectable (and machine-parseable).
-      const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
-
-      for (const dep of component.dependsOn ?? []) {
-        steps.push({
-          name: `Download ${dep} outputs`,
-          uses: "actions/download-artifact@v4",
-          with: { name: artifactName(dep), path: "." },
-        });
-      }
-
-      for (const line of beforeScript) steps.push({ run: line });
-      steps.push({ run: runParts.join(" ") });
-      for (const line of extraScript) steps.push({ run: line });
+      const steps: Array<Record<string, unknown>> = [checkoutStep()];
+      for (const dep of component.dependsOn ?? []) steps.push(downloadArtifactStep(`Download ${dep} outputs`, artifactName(dep), "."));
+      steps.push(...runSteps(beforeScript), { run: runParts.join(" ") }, ...runSteps(extraScript));
 
       // The file holds `<component>=<digest>`; the job output holds the digest.
       if (pinned.has(name)) {
@@ -441,7 +400,7 @@ export function buildGithubPipelineDoc(
       if (dependedUpon.has(name)) {
         steps.push({
           name: `Upload ${name} outputs`,
-          uses: "actions/upload-artifact@v4",
+          uses: UPLOAD_ARTIFACT,
           with: { name: artifactName(name), path: outputsFile(name) },
         });
       }
@@ -450,7 +409,7 @@ export function buildGithubPipelineDoc(
       if (archive) {
         steps.push({
           name: `Upload ${name} build archive`,
-          uses: "actions/upload-artifact@v4",
+          uses: UPLOAD_ARTIFACT,
           with: {
             name: archiveArtifactName(name),
             path: archive.join("\n"),
@@ -461,7 +420,7 @@ export function buildGithubPipelineDoc(
       }
 
       const jobProps: Record<string, unknown> = {
-        "runs-on": "ubuntu-latest",
+        "runs-on": GITHUB_RUNNER,
         ...(needs.length > 0 ? { needs } : {}),
         container: image,
         ...(pinned.has(name) ? { outputs: { digest: "${{ steps.digest.outputs.digest }}" } } : {}),
@@ -472,7 +431,7 @@ export function buildGithubPipelineDoc(
   });
 
   if (promoteTo !== undefined) {
-    const promoteJob = `promote-${toJobName(promoteTo)}`;
+    const promoteJob = `promote-${ciJobName(promoteTo)}`;
     if (promoteJob in jobsDoc) {
       throw new Error(`the promote job "${promoteJob}" has the same name as a component job; rename the component`);
     }
@@ -480,19 +439,13 @@ export function buildGithubPipelineDoc(
     for (const name of [...pinned].sort()) {
       command.push("--digest", `"${name}=\${{ needs.${jobNameByComponent.get(name)!}.outputs.digest }}"`);
     }
-    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
+    const steps: Array<Record<string, unknown>> = [checkoutStep()];
     for (const [name, paths] of archives) {
-      steps.push({
-        name: `Download ${name} build archive`,
-        uses: "actions/download-artifact@v4",
-        with: { name: archiveArtifactName(name), path: artifactRoot(paths) },
-      });
+      steps.push(downloadArtifactStep(`Download ${name} build archive`, archiveArtifactName(name), artifactRoot(paths)));
     }
-    for (const line of beforeScript) steps.push({ run: line });
-    steps.push({ run: command.join(" ") });
-    for (const line of extraScript) steps.push({ run: line });
+    steps.push(...runSteps(beforeScript), { run: command.join(" ") }, ...runSteps(extraScript));
     jobsDoc[promoteJob] = {
-      "runs-on": "ubuntu-latest",
+      "runs-on": GITHUB_RUNNER,
       needs: [...jobNameByComponent.values()].sort(),
       container: image,
       steps,
@@ -558,15 +511,7 @@ function memberArtifactStep(step: Record<string, unknown>, member: PipelineMembe
  * Shared with the forgejo dialect (#969), which transforms the doc first.
  */
 export function emitPipelineYAML(doc: GithubPipelineDoc): string {
-  const sections: string[] = [];
-  sections.push("name: " + emitYAML(doc.name, 0));
-  sections.push(emitYAMLEntry("on", doc.on));
-  if (doc.env && Object.keys(doc.env).length > 0) {
-    sections.push(emitYAMLEntry("env", doc.env));
-  }
-  if (doc.defaults) sections.push(emitYAMLEntry("defaults", doc.defaults));
-  sections.push(emitYAMLEntry("jobs", doc.jobsDoc));
-  return sections.join("\n\n") + "\n";
+  return emitWorkflowYAML({ name: doc.name, on: doc.on, env: doc.env, defaults: doc.defaults, jobsDoc: doc.jobsDoc });
 }
 
 /**