@intentius/chant-lexicon-gitlab 0.79.0 → 0.81.0

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

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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;AAS1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAqFtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAGjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAS1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA8ItB"}

package/dist/integrity.json

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

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -67,8 +67,8 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.79.0",
-    "@intentius/chant-lexicon-github": "^0.79.0",
+    "@intentius/chant": "^0.81.0",
+    "@intentius/chant-lexicon-github": "^0.81.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {

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

@@ -106,7 +106,7 @@
  */
 
 import { emitYAML } from "@intentius/chant/yaml";
-import { resolveOpTrigger } from "@intentius/chant/lexicon";
+import { memberGitlabChanges, memberRepoPath, memberShellDir, resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGitlabOpOptions,
   OpEnvironment,
@@ -425,8 +425,16 @@ export function generateGitlabOpPipeline(
   const extraScript = options.extraScript ?? [];
   const stage = options.opsStage ?? DEFAULT_STAGE;
   assertOpsStage(stage);
-  const fileName = options.opsFileName ?? `${stage}.gitlab-ci.yml`;
-  assertOpsFileName(fileName);
+  const baseFileName = options.opsFileName ?? `${stage}.gitlab-ci.yml`;
+  assertOpsFileName(baseFileName);
+  // A workspace member's file, jobs and resource groups carry its name
+  // (#2542): the root .gitlab-ci.yml includes every member's file, and job
+  // names share one namespace across them.
+  const member = options.member;
+  const fileName = member ? `${member.name}-${baseFileName}` : baseFileName;
+  const jobPrefix = member ? `${member.name}-` : "";
+  const changes = member ? memberGitlabChanges(member, member.fileDir ? `${member.fileDir}/${fileName}` : undefined) : undefined;
+  const cdLine = member && member.dir !== "." && member.dir !== "" ? [`cd ${memberShellDir(member)}`] : [];
 
   const jobs: OpPipelineJob[] = [];
   const doc: Record<string, unknown> = { stages: [stage] };
@@ -443,7 +451,7 @@ export function generateGitlabOpPipeline(
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
     if (trigger.kind === "cron") anyCron = true;
 
-    const jobName = toJobName(spec.name);
+    const jobName = jobPrefix + toJobName(spec.name);
     jobs.push({ jobName, op: spec.name, trigger, findingMode });
     opLines.push(headerLineFor(spec, trigger, jobName, findingMode));
     if (spec.environment) {
@@ -484,14 +492,14 @@ export function generateGitlabOpPipeline(
           }
         : {}),
       ...(Object.keys(jobVariables).length > 0 ? { variables: jobVariables } : {}),
-      rules: rulesFor(spec, trigger),
-      script: [...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+      rules: changes && trigger.kind !== "cron" ? rulesFor(spec, trigger).map((r) => ({ ...r, changes })) : rulesFor(spec, trigger),
+      script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
       // `when: always` because the run this publishes for is the green one: a
       // gated apply succeeds, and the block is the only thing that says a
       // human still has to act. A run that walked through its gate writes no
       // block, and GitLab reports the empty upload as a warning, not a failure.
       ...(gated
-        ? { artifacts: { when: "always", paths: [gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
+        ? { artifacts: { when: "always", paths: [member ? memberRepoPath(member, gateSummary) : gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
         : {}),
     };
   }

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

@@ -0,0 +1,98 @@
+/**
+ * A workspace member's pipelines on GitLab (#2542, #2524 D19). GitLab reads
+ * one .gitlab-ci.yml, which includes each member's file, so job names carry
+ * the member's name and each job carries its own `rules: changes:`.
+ */
+
+import { describe, test, expect } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import type { PipelineMember } from "@intentius/chant/lexicon";
+import { generateGitlabPipeline } from "./generate-pipeline";
+import { generateGitlabOpPipeline } from "./generate-op-pipeline";
+
+const components: DriverComponent[] = [
+  { name: "shared-alb", dependsOn: [], deploy: [] },
+  {
+    name: "api",
+    dependsOn: ["shared-alb"],
+    deploy: [
+      { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: "dist/api.tar" }] },
+      { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:dist/api.tar" }] },
+    ],
+  },
+];
+
+const api: PipelineMember = { name: "api", dir: "services/api", file: ".gitlab/ci/chant-api-staging.gitlab-ci.yml" };
+
+type Job = { script: string[]; needs?: string[]; rules?: unknown[]; artifacts?: { paths: string[] }; stage: string };
+
+describe("generateGitlabPipeline for a workspace member", () => {
+  test("jobs take the member's name, run in its directory and only on its changes", () => {
+    const result = generateGitlabPipeline(components, { env: "staging", member: api });
+    const doc = parseYAML(result.yaml) as Record<string, unknown>;
+    expect(doc.workflow).toEqual({ name: "chant-components-api-staging" });
+    expect(doc["shared-alb"]).toBeUndefined();
+
+    const job = doc["api-api"] as Job;
+    expect(job.script).toEqual(["cd services/api", "chant run --components api --env staging --seed-outputs shared-alb.outputs.json"]);
+    expect(job.needs).toEqual(["api-shared-alb"]);
+    expect(job.rules).toEqual([{ changes: ["services/api/**/*", ".gitlab/ci/chant-api-staging.gitlab-ci.yml"] }]);
+
+    const shared = doc["api-shared-alb"] as Job;
+    expect(shared.artifacts).toEqual({ paths: ["services/api/shared-alb.outputs.json"] });
+
+    expect(result.jobs.map((j) => [j.jobName, j.needs])).toEqual([
+      ["api-shared-alb", []],
+      ["api-api", ["api-shared-alb"]],
+    ]);
+  });
+
+  test("the promote job is renamed and needs the renamed jobs; archive paths move under the member", () => {
+    const doc = parseYAML(generateGitlabPipeline(components, { env: "staging", promoteTo: "prod", member: api }).yaml) as Record<string, unknown>;
+    const promote = doc["api-promote-prod"] as Job;
+    expect(promote.needs).toEqual(["api-api", "api-shared-alb"]);
+    expect(promote.script[0]).toBe("cd services/api");
+    expect((doc["api-api"] as Job).artifacts?.paths).toEqual(["services/api/dist/api.tar", "services/api/api.digest"]);
+    // The promote job reads the digest file after its cd, from where the api job wrote it (#2602).
+    expect(promote.script[1]).toContain('--digest "api=$(cut -d= -f2- api.digest)"');
+    expect(doc.stages).toEqual(["wave-1", "wave-2", "promote"]);
+  });
+
+  test("a member at the root has no changes rule, since GitLab's changes can't exclude the other members", () => {
+    const doc = parseYAML(generateGitlabPipeline(components, { env: "prod", member: { name: "platform", dir: ".", exclude: ["services/api"] } }).yaml) as Record<string, unknown>;
+    const job = doc["platform-api"] as Job;
+    expect(job.rules).toBeUndefined();
+    expect(job.script[0]).toMatch(/^chant run/);
+  });
+
+  test("a directory with a space is quoted for cd", () => {
+    const doc = parseYAML(generateGitlabPipeline(components, { env: "prod", member: { name: "odd", dir: "my apps/odd" } }).yaml) as Record<string, unknown>;
+    expect((doc["odd-api"] as Job).script[0]).toBe("cd 'my apps/odd'");
+  });
+});
+
+describe("generateGitlabOpPipeline for a workspace member", () => {
+  const member: PipelineMember = { name: "api", dir: "services/api", fileDir: ".gitlab/ci" };
+
+  test("the file and job names carry the member, push and merge-request rules gain changes, cron does not", () => {
+    const result = generateGitlabOpPipeline(
+      [
+        { name: "nightly", trigger: { kind: "cron", schedule: "0 6 * * *" } },
+        { name: "plan", trigger: { kind: "pull_request" } },
+        { name: "apply", trigger: { kind: "push" } },
+      ],
+      { member },
+    );
+    expect(result.files.map((f) => f.name)).toEqual(["api-ops.gitlab-ci.yml"]);
+    const doc = parseYAML(result.files[0].yaml) as Record<string, Omit<Job, "rules"> & { resource_group: string; rules: Array<Record<string, unknown>> }>;
+    const changes = ["services/api/**/*", ".gitlab/ci/api-ops.gitlab-ci.yml"];
+
+    expect(doc["api-nightly"].rules.every((r) => !("changes" in r))).toBe(true);
+    expect(doc["api-plan"].rules.every((r) => JSON.stringify(r.changes) === JSON.stringify(changes))).toBe(true);
+    expect(doc["api-apply"].rules.every((r) => JSON.stringify(r.changes) === JSON.stringify(changes))).toBe(true);
+    expect(doc["api-apply"].resource_group).toBe("api-apply");
+    expect(doc["api-apply"].script[0]).toBe("cd services/api");
+    expect(doc["api-apply"].artifacts?.paths).toEqual(["services/api/chant-gate-api-apply.md"]);
+  });
+});

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

@@ -257,3 +257,73 @@ describe("generateGitlabPipeline: options", () => {
     expect((job.script as string[])[0]).toContain("--env production");
   });
 });
+
+describe("generateGitlabPipeline: a promote job (#2575)", () => {
+  const components = (): DriverComponent[] => [
+    { name: "shared-alb", dependsOn: [], deploy: [] },
+    {
+      name: "api",
+      dependsOn: ["shared-alb"],
+      deploy: [
+        { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: "dist/api.tar" }] },
+        { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:dist/api.tar" }] },
+      ],
+    },
+  ];
+
+  test("without promoteTo the pipeline is unchanged", () => {
+    const yaml = generateGitlabPipeline(components(), { env: "staging" }).yaml;
+    expect(yaml).not.toContain("promote");
+    expect(yaml).not.toContain("dist/api.tar");
+  });
+
+  test("building jobs keep their archive as artifacts, and a promote stage job needs every component job", () => {
+    const result = generateGitlabPipeline(components(), { env: "staging", promoteTo: "prod" });
+    const parsed = parseYAML(result.yaml);
+
+    expect((parsed["api"] as Record<string, unknown>).artifacts).toEqual({ paths: ["dist/api.tar", "api.digest"] });
+    expect((parsed["shared-alb"] as Record<string, unknown>).artifacts).toEqual({ paths: ["shared-alb.outputs.json"] });
+
+    expect(parsed.stages).toEqual(["wave-1", "wave-2", "promote"]);
+    expect(result.stages).toEqual(["wave-1", "wave-2"]);
+    expect(parsed["promote-prod"]).toEqual({
+      stage: "promote",
+      image: "node:22-slim",
+      script: ['chant components promote --from staging --to prod --digest "api=$(cut -d= -f2- api.digest)"'],
+      needs: ["api", "shared-alb"],
+    });
+  });
+
+  test("the promote job promotes the digest this pipeline's component job recorded (#2602)", () => {
+    const parsed = parseYAML(generateGitlabPipeline(components(), { env: "staging", promoteTo: "prod" }).yaml);
+    const job = (name: string) => parsed[name] as { script: string[]; artifacts?: { paths: string[] } };
+
+    // The component job writes the digest its run recorded, and keeps the file
+    // as an artifact, which GitLab hands to the promote job across `needs:`.
+    expect(job("api").script).toEqual(["chant run --components api --env staging --seed-outputs shared-alb.outputs.json --digest-file api.digest"]);
+    expect(job("api").artifacts?.paths).toContain("api.digest");
+    // shared-alb publishes nothing, so it records no release and is not pinned.
+    expect(job("shared-alb").script[0]).not.toContain("--digest-file");
+
+    const promote = job("promote-prod").script[0];
+    expect(promote).toContain('--digest "api=$(cut -d= -f2- api.digest)"');
+    expect(promote).not.toContain("shared-alb=");
+  });
+
+  test("promoteCommand still gets the pinned digests", () => {
+    const parsed = parseYAML(generateGitlabPipeline(components(), {
+      env: "staging",
+      promoteTo: "prod",
+      promoteCommand: ["npx", "chant", "components", "promote", "--from", "staging", "--to", "prod"],
+    }).yaml);
+    expect((parsed["promote-prod"] as { script: string[] }).script).toEqual([
+      'npx chant components promote --from staging --to prod --digest "api=$(cut -d= -f2- api.digest)"',
+    ]);
+  });
+
+  test("with no component that publishes, there is no release to pin, and generation fails", () => {
+    const infraOnly: DriverComponent[] = [{ name: "shared-alb", dependsOn: [], deploy: [] }];
+    expect(() => generateGitlabPipeline(infraOnly, { promoteTo: "prod" })).toThrow(/no component has a publish step/);
+    expect(() => generateGitlabPipeline(infraOnly)).not.toThrow();
+  });
+});

package/src/components/generate-pipeline.ts

@@ -34,10 +34,13 @@
 
 import { emitYAML } from "@intentius/chant/yaml";
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
+import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
+import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
   ComponentPipelineOptions as GenerateGitlabOptions,
   ComponentPipelineResult as GenerateGitlabResult,
+  PipelineMember,
 } from "@intentius/chant/lexicon";
 
 export type { GeneratedJob, GenerateGitlabOptions, GenerateGitlabResult };
@@ -82,6 +85,29 @@ export function generateGitlabPipeline(
   for (const c of components) for (const dep of c.dependsOn ?? []) dependedUpon.add(dep);
   const outputsFile = (name: string) => `${name}.outputs.json`;
 
+  // A promote job (#2575) runs apart from the deploy jobs, and a promote
+  // publishes from the build archive on disk, so each component job keeps the
+  // files its build steps wrote as artifacts. GitLab hands them to the promote
+  // job across its `needs:` edges. Each component job with a publish step
+  // also keeps the digest its run recorded (`--digest-file`), and the promote
+  // job passes it back as `--digest <component>=<digest>` (#2602), so it
+  // promotes the release this run built rather than whatever is latest in the
+  // source environment.
+  const promoteTo = options.promoteTo;
+  const archives = new Map<string, string[]>();
+  const pinned = new Set<string>();
+  const digestFile = (name: string) => `${name}.digest`;
+  if (promoteTo !== undefined) {
+    for (const c of components) {
+      const paths = promoteArchivePaths(c);
+      if (paths.length > 0) archives.set(c.name, paths);
+      if (hasPublishStep(c)) pinned.add(c.name);
+    }
+    if (pinned.size === 0) {
+      throw new Error("no component has a publish step, so no deploy records a release for the promote job to promote");
+    }
+  }
+
   const stages = waves.map((_, i) => `wave-${i + 1}`);
   const jobs: GeneratedJob[] = [];
   const jobNameByComponent = new Map<string, string>();
@@ -115,6 +141,7 @@ export function generateGitlabPipeline(
       const runParts = runCommand.map((part) => part.replace("{name}", 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));
 
       const script = [...beforeScript, runParts.join(" "), ...extraScript];
 
@@ -125,11 +152,40 @@ export function generateGitlabPipeline(
       };
       if (needs.length > 0) jobProps.needs = needs;
       // Publish this component's dumped outputs so dependent jobs receive it.
-      if (dependedUpon.has(name)) jobProps.artifacts = { paths: [outputsFile(name)] };
+      const artifactPaths = [
+        ...(dependedUpon.has(name) ? [outputsFile(name)] : []),
+        ...(archives.get(name) ?? []),
+        ...(pinned.has(name) ? [digestFile(name)] : []),
+      ];
+      if (artifactPaths.length > 0) jobProps.artifacts = { paths: artifactPaths };
       doc[jobName] = jobProps;
     }
   });
 
+  let promoteJob: string | undefined;
+  if (promoteTo !== undefined) {
+    promoteJob = `promote-${toJobName(promoteTo)}`;
+    if (promoteJob in doc) {
+      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])];
+    // The file holds `<component>=<digest>`; a missing or empty one leaves
+    // `<component>=`, which the promote refuses.
+    for (const name of [...pinned].sort()) {
+      command.push("--digest", `"${name}=$(cut -d= -f2- ${digestFile(name)})"`);
+    }
+    doc[promoteJob] = {
+      stage: "promote",
+      image,
+      script: [...beforeScript, command.join(" "), ...extraScript],
+      needs: [...jobNameByComponent.values()].sort(),
+    };
+  }
+
+  if (options.member) {
+    promoteJob = scopeToMember(doc, jobs, promoteJob, options.member, env);
+  }
+
   const sections: string[] = [];
   // `emitYAML` returns a `\n`-led block for a non-empty sequence and an inline
   // `[]` for an empty one, so the header needs a space in the second case.
@@ -137,12 +193,61 @@ export function generateGitlabPipeline(
   // when whitespace or the line's end follows it — which is how GitLab's own
   // reader takes it, and now how `parseYAML` does too (chant #2013).
   sections.push("workflow:" + emitYAML(doc.workflow, 1));
-  sections.push(stages.length > 0 ? "stages:" + emitYAML(stages, 1) : "stages: []");
+  // The promote stage is YAML only: `stages` in the result stays one entry
+  // per graph wave.
+  const yamlStages = promoteJob ? [...stages, "promote"] : stages;
+  sections.push(yamlStages.length > 0 ? "stages:" + emitYAML(yamlStages, 1) : "stages: []");
   if (doc.variables) sections.push("variables:" + emitYAML(doc.variables, 1));
   for (const job of jobs) {
     const props = doc[job.jobName] as Record<string, unknown>;
     sections.push(`${job.jobName}:` + emitYAML(props, 1));
   }
+  if (promoteJob) sections.push(`${promoteJob}:` + emitYAML(doc[promoteJob], 1));
 
   return { yaml: sections.join("\n\n") + "\n", stages, jobs, env };
 }
+
+/**
+ * Scope a pipeline to one workspace member (#2542, #2524 D19), in place on
+ * `doc` and `jobs`. Returns the promote job's new name.
+ *
+ * GitLab reads one `.gitlab-ci.yml`, so a member's pipeline is a file that
+ * the root file includes, and job names share one namespace across every
+ * included file. Each job therefore takes the member's name as a prefix. A
+ * `rules: changes:` entry limits each job to changes under the member's
+ * directory or to the pipeline file; for a member at `"."` there is no such
+ * rule, since `changes` has no exclusions. Each job's script starts with a
+ * `cd` into the member's directory, and artifact paths, which GitLab resolves
+ * against the repository root, move under it.
+ */
+function scopeToMember(
+  doc: Record<string, unknown>,
+  jobs: GeneratedJob[],
+  promoteJob: string | undefined,
+  member: PipelineMember,
+  env: string,
+): string | undefined {
+  const rooted = member.dir === "." || member.dir === "";
+  const changes = memberGitlabChanges(member);
+  const renamed = new Map<string, string>();
+  for (const job of jobs) renamed.set(job.jobName, `${member.name}-${job.jobName}`);
+  if (promoteJob) renamed.set(promoteJob, `${member.name}-${promoteJob}`);
+
+  for (const [from, to] of renamed) {
+    const props = doc[from] as Record<string, unknown>;
+    delete doc[from];
+    const next: Record<string, unknown> = { ...props };
+    if (!rooted) next.script = [`cd ${memberShellDir(member)}`, ...(props.script as string[])];
+    if (Array.isArray(props.needs)) next.needs = (props.needs as string[]).map((n) => renamed.get(n) ?? n);
+    const artifacts = props.artifacts as { paths?: string[] } | undefined;
+    if (artifacts?.paths) next.artifacts = { ...artifacts, paths: artifacts.paths.map((p) => memberRepoPath(member, p)) };
+    if (changes) next.rules = [{ changes }];
+    doc[to] = next;
+  }
+  for (const job of jobs) {
+    job.jobName = renamed.get(job.jobName)!;
+    job.needs = job.needs.map((n) => renamed.get(n) ?? n);
+  }
+  doc.workflow = { name: `chant-components-${member.name}-${env}` };
+  return promoteJob ? renamed.get(promoteJob) : undefined;
+}