@intentius/chant-lexicon-github 0.79.0 → 0.80.0

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

@@ -88,6 +88,12 @@ export interface GithubOpPipelineDoc {
      * rather than only in a build warning.
      */
     header?: string[];
+    /**
+     * The workflow's `name:` (#2580): the Op's name, so the Actions UI lists
+     * the workflow by its Op instead of its file name. The forgejo dialect
+     * does not copy it, so forgejo output is unchanged.
+     */
+    name?: string;
     /**
      * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
      * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`

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;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EACnD,aAAa,EAEb,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,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,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;;;;;;;;;OASG;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;AAmUD;;;;;;;;;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;;;;;GAKG;AACH,MAAM,WAAW,wCAAwC;IACvD;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,EACrC,eAAe,GAAE,wCAA6C,GAC7D;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CA6F1D;AAED;;;;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;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EACnD,aAAa,EAEb,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,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;;;;;;;;;OASG;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;AAmUD;;;;;;;;;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;;;;;GAKG;AACH,MAAM,WAAW,wCAAwC;IACvD;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,EACrC,eAAe,GAAE,wCAA6C,GAC7D;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CA8F1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAgBnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}

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

@@ -35,6 +35,10 @@
  *    uses, and matches gitlab's artifact-passing 1:1 in intent — only the
  *    transport differs (explicit upload/download steps vs. GitLab's implicit
  *    `needs:` artifact passing).
+ *  - With `options.promoteTo` (#2575), one more job needs every component
+ *    job and runs `chant components promote`. A promote publishes from the
+ *    build archive on disk, so each component job uploads the files its
+ *    build steps wrote and the promote job downloads them to the same paths.
  *
  * Cross-cutting changes (e.g. "sign every image before deploy") are made by
  * editing `GenerateGithubOptions.extraScript`/`beforeScript` (or the
@@ -80,6 +84,12 @@ export interface GithubPipelineDoc {
     /** Every generated job, for the machine-readable view. */
     jobs: GeneratedJob[];
 }
+/**
+ * The directory `actions/upload-artifact` roots a set of files at: the
+ * deepest directory that holds all of them. Downloading into it puts each
+ * file back at the path it was uploaded from.
+ */
+export declare function artifactRoot(paths: string[]): string;
 /**
  * Synthesize a `.github/workflows/*.yml` pipeline from a set of components:
  * one job per component, `needs:` expressing the wave-ordered dependency DAG

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAChD,MAAM,0BAA0B,CAAC;AAElC,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;;;;;;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;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA0FnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAS/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAEjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAChD,MAAM,0BAA0B,CAAC;AAElC,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;;;;;;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;AAwBD;;;;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,CA6InB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAS/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": "ced24be037a4771c506d5c508c101750dc089c8b26dece0259cfca096577175b",
+    "manifest.json": "7c9fa1fee6182c66eda6e2ea0f281b518e72064c620740702f1c48dfbbdd46f1",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "bdd54a4145a39a9dd4f7bbc8c500191acb6bc9057a87da0040475afac84db397",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -77,5 +77,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "06574aff8eec2ef2e8bcbd09e2f1012920840d23301938b7e12d286984e12e80"
+  "composite": "1809da7db679ed9d9380d1fa046864be900a4d0b5e5209152dfd61d5460dde3f"
 }

package/dist/manifest.json

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

package/package.json

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

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

@@ -597,10 +597,13 @@ describe("generateGithubOpPipeline: a deployment environment on the Op's job (#2
    * The exact document a spec with no `environment` emitted before the option
    * existed, produced by the generator at the commit this change branched
    * from. The claim the option makes is that it is additive; this is what
-   * makes that claim falsifiable rather than a sentence in a PR body.
+   * makes that claim falsifiable rather than a sentence in a PR body. The
+   * `name:` line came later, from #2580, for every spec alike.
    */
   const AUDIT_YAML_BEFORE_2257 =
     [
+      "name: actions-audit",
+      "",
       "on:",
       "  schedule:",
       "    - cron: '0 6 * * *'",

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

@@ -102,6 +102,12 @@ export interface GithubOpPipelineDoc {
    * rather than only in a build warning.
    */
   header?: string[];
+  /**
+   * The workflow's `name:` (#2580): the Op's name, so the Actions UI lists
+   * the workflow by its Op instead of its file name. The forgejo dialect
+   * does not copy it, so forgejo output is unchanged.
+   */
+  name?: string;
   /**
    * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
    * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`
@@ -713,6 +719,7 @@ export function buildGithubOpPipelineDocs(
     for (const line of extraScript) steps.push({ run: line });
 
     const doc: GithubOpPipelineDoc = {
+      name: spec.name,
       on: onFor(trigger),
       ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
       // One run at a time per Op — a slow audit must not overlap its own next
@@ -771,6 +778,7 @@ export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
   // 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("on:" + emitYAML(doc.on, 1));
   if (doc.env && Object.keys(doc.env).length > 0) sections.push("env:" + emitYAML(doc.env, 1));
   sections.push("concurrency:" + emitYAML(doc.concurrency, 1));

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

@@ -19,7 +19,7 @@
 
 import { describe, test, expect } from "vitest";
 import { parseYAML } from "@intentius/chant/yaml";
-import { generateGithubPipeline } from "./generate-pipeline";
+import { artifactRoot, generateGithubPipeline } from "./generate-pipeline";
 import { resolveComponentGraph, DependencyCycleError, UnknownDependencyError, type DriverComponent } from "@intentius/chant/components/driver";
 import { searchService } from "@intentius/chant/components/pilots/alb-ecs.pilot";
 import { ordersTable } from "@intentius/chant/components/pilots/dynamodb.pilot";
@@ -295,3 +295,93 @@ describe("generateGithubPipeline: options", () => {
     expect(runLines(jobs["shared-alb"])[0]).toContain("--env production");
   });
 });
+
+/** Two services that build and publish, one depending on the other, plus infra that builds nothing. */
+function promotableComponents(): DriverComponent[] {
+  const service = (name: string, into: string, dependsOn: string[] = []): DriverComponent => ({
+    name,
+    dependsOn,
+    deploy: [
+      { phase: "Build", steps: [{ kind: "docker-build", context: ".", into }] },
+      { phase: "Publish", steps: [{ kind: "publish-image", from: `archive:${into}`, to: "$env.registry" }] },
+    ],
+  });
+  return [
+    { name: "shared-alb", dependsOn: [], deploy: [] },
+    service("api", "dist/images/api.tar", ["shared-alb"]),
+    service("worker", "worker.tar"),
+  ];
+}
+
+describe("generateGithubPipeline: a promote job (#2575)", () => {
+  test("without promoteTo the pipeline is unchanged: no archive upload, no promote job", () => {
+    const yaml = generateGithubPipeline(promotableComponents(), { env: "staging" }).yaml;
+    expect(yaml).not.toContain("promote");
+    expect(yaml).not.toContain("build archive");
+  });
+
+  test("each building job uploads its archive, and the promote job downloads it back to the same path", () => {
+    const result = generateGithubPipeline(promotableComponents(), { env: "staging", promoteTo: "prod" });
+    const jobs = parsedJobs(result.yaml);
+
+    const upload = jobs["api"].steps.find((s) => s.name === "Upload api build archive")!;
+    expect(upload.uses).toBe("actions/upload-artifact@v4");
+    expect(upload.with).toEqual({
+      name: "api-archive",
+      path: "dist/images/api.tar",
+      "if-no-files-found": "error",
+      "include-hidden-files": true,
+    });
+    expect(jobs["shared-alb"].steps.some((s) => s.name?.includes("build archive"))).toBe(false);
+
+    const promote = jobs["promote-prod"];
+    expect(promote.needs).toEqual(["api", "shared-alb", "worker"]);
+    expect(promote.container).toBe("node:22-slim");
+    const downloads = promote.steps.filter((s) => s.uses === "actions/download-artifact@v4");
+    expect(downloads.map((s) => s.with)).toEqual([
+      { name: "api-archive", path: "dist/images" },
+      { name: "worker-archive", path: "." },
+    ]);
+    expect(runLines(promote)).toEqual(["chant components promote --from staging --to prod"]);
+
+    // The machine-readable views stay one entry per component.
+    expect(result.jobs.map((j) => j.component).sort()).toEqual(["api", "shared-alb", "worker"]);
+  });
+
+  test("the promote job runs the same beforeScript and extraScript, and promoteCommand replaces its command", () => {
+    const result = generateGithubPipeline(promotableComponents(), {
+      env: "staging",
+      promoteTo: "prod",
+      beforeScript: ["npm ci"],
+      extraScript: ["echo done"],
+      promoteCommand: ["npx", "chant", "components", "promote", "--from", "staging", "--to", "prod"],
+    });
+    expect(runLines(parsedJobs(result.yaml)["promote-prod"])).toEqual([
+      "npm ci",
+      "npx chant components promote --from staging --to prod",
+      "echo done",
+    ]);
+  });
+
+  test("a build step writing to a path known only at run time is refused", () => {
+    const components: DriverComponent[] = [
+      { name: "api", deploy: [{ phase: "Build", steps: [{ kind: "docker-build", into: "$env.archive" }] }] },
+    ];
+    expect(() => generateGithubPipeline(components, { promoteTo: "prod" })).toThrow(/not a literal path/);
+    expect(() => generateGithubPipeline(components)).not.toThrow();
+  });
+
+  test("a component whose job name is the promote job's is refused", () => {
+    const components: DriverComponent[] = [{ name: "promote-prod", deploy: [] }];
+    expect(() => generateGithubPipeline(components, { promoteTo: "prod" })).toThrow(/same name as a component job/);
+  });
+
+  test("artifactRoot is the deepest directory holding every file", () => {
+    expect(artifactRoot(["archive"])).toBe(".");
+    expect(artifactRoot(["dist/a.tar"])).toBe("dist");
+    expect(artifactRoot(["dist/a/x.tar", "dist/b/y.zip"])).toBe("dist");
+    expect(artifactRoot(["dist/a.tar", "b.zip"])).toBe(".");
+    expect(artifactRoot(["./dist/a.tar"])).toBe("dist");
+    expect(artifactRoot(["/tmp/out/a.tar", "/tmp/out/b.tar"])).toBe("/tmp/out");
+  });
+});

package/src/components/generate-pipeline.ts

@@ -35,6 +35,10 @@
  *    uses, and matches gitlab's artifact-passing 1:1 in intent — only the
  *    transport differs (explicit upload/download steps vs. GitLab's implicit
  *    `needs:` artifact passing).
+ *  - With `options.promoteTo` (#2575), one more job needs every component
+ *    job and runs `chant components promote`. A promote publishes from the
+ *    build archive on disk, so each component job uploads the files its
+ *    build steps wrote and the promote job downloads them to the same paths.
  *
  * Cross-cutting changes (e.g. "sign every image before deploy") are made by
  * editing `GenerateGithubOptions.extraScript`/`beforeScript` (or the
@@ -46,6 +50,7 @@
 
 import { emitYAML } from "@intentius/chant/yaml";
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
+import { promoteArchivePaths } from "@intentius/chant/components/promote";
 import type {
   ComponentPipelineJob as GeneratedJob,
   ComponentPipelineOptions as GenerateGithubOptions,
@@ -106,6 +111,29 @@ function artifactName(name: string): string {
   return `${name}-outputs`;
 }
 
+/** The workflow artifact name a component's build archive is uploaded under, for the promote job (#2575). */
+function archiveArtifactName(name: string): string {
+  return `${name}-archive`;
+}
+
+/**
+ * The directory `actions/upload-artifact` roots a set of files at: the
+ * deepest directory that holds all of them. Downloading into it puts each
+ * file back at the path it was uploaded from.
+ */
+export function artifactRoot(paths: string[]): string {
+  const dirs = paths.map((p) => {
+    const parts = p.replace(/\/+$/, "").split("/");
+    parts.pop();
+    return parts.filter((part) => part !== "" && part !== ".");
+  });
+  const common: string[] = [];
+  for (let i = 0; dirs.every((d) => i < d.length && d[i] === dirs[0][i]); i++) common.push(dirs[0][i]);
+  const absolute = paths.every((p) => p.startsWith("/"));
+  if (common.length === 0) return absolute ? "/" : ".";
+  return (absolute ? "/" : "") + common.join("/");
+}
+
 /**
  * Synthesize a `.github/workflows/*.yml` pipeline from a set of components:
  * one job per component, `needs:` expressing the wave-ordered dependency DAG
@@ -139,6 +167,18 @@ export function buildGithubPipelineDoc(
   const dependedUpon = new Set<string>();
   for (const c of components) for (const dep of c.dependsOn ?? []) dependedUpon.add(dep);
 
+  // A promote job (#2575) runs on its own runner, and a promote publishes from
+  // the build archive on disk, so each component job uploads the files its
+  // build steps wrote and the promote job downloads them.
+  const promoteTo = options.promoteTo;
+  const archives = new Map<string, string[]>();
+  if (promoteTo !== undefined) {
+    for (const c of components) {
+      const paths = promoteArchivePaths(c);
+      if (paths.length > 0) archives.set(c.name, paths);
+    }
+  }
+
   const stages = waves.map((_, i) => `wave-${i + 1}`);
   const jobs: GeneratedJob[] = [];
   const jobNameByComponent = new Map<string, string>();
@@ -189,6 +229,20 @@ export function buildGithubPipelineDoc(
         });
       }
 
+      const archive = archives.get(name);
+      if (archive) {
+        steps.push({
+          name: `Upload ${name} build archive`,
+          uses: "actions/upload-artifact@v4",
+          with: {
+            name: archiveArtifactName(name),
+            path: archive.join("\n"),
+            "if-no-files-found": "error",
+            "include-hidden-files": true,
+          },
+        });
+      }
+
       const jobProps: Record<string, unknown> = {
         "runs-on": "ubuntu-latest",
         ...(needs.length > 0 ? { needs } : {}),
@@ -199,6 +253,31 @@ export function buildGithubPipelineDoc(
     }
   });
 
+  if (promoteTo !== undefined) {
+    const promoteJob = `promote-${toJobName(promoteTo)}`;
+    if (promoteJob in jobsDoc) {
+      throw new Error(`the promote job "${promoteJob}" has the same name as a component job; rename the component`);
+    }
+    const command = options.promoteCommand ?? ["chant", "components", "promote", "--from", env, "--to", promoteTo];
+    const steps: Array<Record<string, unknown>> = [{ uses: "actions/checkout@v4" }];
+    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) },
+      });
+    }
+    for (const line of beforeScript) steps.push({ run: line });
+    steps.push({ run: command.join(" ") });
+    for (const line of extraScript) steps.push({ run: line });
+    jobsDoc[promoteJob] = {
+      "runs-on": "ubuntu-latest",
+      needs: [...jobNameByComponent.values()].sort(),
+      container: image,
+      steps,
+    };
+  }
+
   return {
     name: `chant-components-${env}`,
     environment: env,