@intentius/chant-lexicon-gitlab 0.124.52 → 0.124.55

package/src/components/control-pipeline.ts

@@ -0,0 +1,38 @@
+/**
+ * The control repo's own pipeline (#4568) on GitLab: a member's pipeline
+ * trigger starts it with `CHANT_CONTROL_MEMBER` and `CHANT_CONTROL_OP` set,
+ * and its one job runs the member's dependents with `chant workspace run
+ * --dependents-of`. The pieces are core's (`controlPipelineSpec` in
+ * `@intentius/chant/control/dispatch`); the file is one the control repo's
+ * `.gitlab-ci.yml` includes. The member's side, the `control-dispatch` job,
+ * comes from the pull request loop's `control` option
+ * (./generate-pipeline.ts).
+ */
+
+import { CI_IMAGE, GITLAB_FULL_HISTORY } from "@intentius/chant/ci-jobs";
+import { controlPipelineSpec } from "@intentius/chant/control/dispatch";
+import type { CiProductWords, CiProductWordsInput } from "@intentius/chant/ci-product-words";
+import { emitGitlabFile } from "./ci-jobs";
+
+/** A control repo's pipeline file: where it goes, its text, and what a person still sets up. */
+export interface ControlPipelineFile {
+  path: string;
+  content: string;
+  notes: string[];
+}
+
+/** The control repo's pipeline on GitLab: `.gitlab/<product>-dependents.yml`. */
+export function generateControlPipeline(options: { words?: CiProductWordsInput | CiProductWords; image?: string; command?: string } = {}): ControlPipelineFile {
+  const spec = controlPipelineSpec("gitlab", options.words ?? {}, options.command ? { command: options.command } : {});
+  const job = {
+    stage: "deploy",
+    image: options.image ?? CI_IMAGE,
+    // The full history, so the job reads and appends to chant/lifecycle (#4617).
+    variables: { ...GITLAB_FULL_HISTORY },
+    rules: [{ if: spec.rule }],
+    // One member at a time: two applies upstream should not run the same dependents side by side.
+    resource_group: spec.group,
+    script: [`bash <<'DEPENDENTS' || exit $?\n${spec.script}\nDEPENDENTS`],
+  };
+  return { path: spec.path, content: emitGitlabFile([["dependents", job]], spec.header), notes: spec.notes };
+}

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

@@ -0,0 +1,99 @@
+/**
+ * The agent jobs on GitLab (#4616): the comment agent in a pipeline of the
+ * default branch started with the merge request and the ask, the drift agent
+ * after a drift check, the push token scoped to the push job's environment,
+ * and a runner as tags.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateGitlabOpPipeline } from "./generate-op-pipeline";
+
+type Job = { rules?: Array<{ if?: string; when?: string }>; needs?: Array<{ job: string }>; tags?: string[]; timeout?: string; environment?: { name: string }; script: string[]; artifacts?: { paths?: string[]; reports?: Record<string, string> }; variables?: Record<string, string> };
+const gen = (spec: ScheduledOpSpec) => {
+  const out = generateGitlabOpPipeline([spec]);
+  return { doc: parseYAML(out.files[0]!.yaml) as unknown as Record<string, Job>, yaml: out.files[0]!.yaml };
+};
+
+describe("the comment agent on GitLab", () => {
+  const { doc, yaml } = gen({ name: "chant-agent", runner: ["agents"], agent: { on: "comment", comment: "/chant agent", maxRuns: 4 } });
+  const agent = doc["chant-agent"]!;
+  const push = doc["chant-agent-push"]!;
+
+  test("runs in a pipeline of the default branch started with the merge request and the ask", () => {
+    expect(agent.rules?.[0]?.if).toContain("$CHANT_AGENT_PR =~ /^[0-9]+$/");
+    expect(agent.rules?.[0]?.if).toContain("$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH");
+    expect(agent.tags).toEqual(["agents"]);
+    expect(agent.timeout).toBe("45 minutes");
+  });
+
+  test("the agent job drops every forge token before the decision and the model", () => {
+    const unset = agent.script.findIndex((l) => l.startsWith("unset "));
+    const prepare = agent.script.findIndex((l) => l.includes("chant agent prepare"));
+    expect(unset).toBeGreaterThan(-1);
+    expect(unset).toBeLessThan(prepare);
+    expect(agent.script.at(-1)).toContain("chant agent run --forge gitlab");
+    expect(agent.artifacts?.paths).toEqual([".chant/agent"]);
+  });
+
+  test("the push job runs under its own environment with the push token", () => {
+    expect(push.environment?.name).toBe("chant-agent-push");
+    expect(push.needs).toEqual([{ job: "chant-agent", artifacts: true }]);
+    expect(push.script.join("\n")).toContain('export CHANT_GITLAB_TOKEN="$CHANT_FORGE_TOKEN"');
+    expect(push.script.at(-1)).toContain("chant agent land --forge gitlab");
+    expect(yaml).toContain("scope it to environment chant-agent-push");
+  });
+});
+
+describe("the drift agent on GitLab", () => {
+  const { doc } = gen({ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, agent: { on: "drift" } });
+
+  test("the drift check keeps its output and a dotenv that says it found drift", () => {
+    const op = doc["drift-app"]!;
+    expect(op.script.join("\n")).toContain('echo "CHANT_AGENT_DRIFT=1"');
+    expect(op.artifacts?.reports).toEqual({ dotenv: ".chant/agent/drift.env" });
+  });
+
+  test("the agent and push jobs follow it whatever it exited, and stop when it found none", () => {
+    const agent = doc["drift-app-agent"]!;
+    expect(agent.needs).toEqual([{ job: "drift-app", artifacts: true }]);
+    expect(agent.rules?.every((r) => r.when === "always")).toBe(true);
+    expect(agent.script[0]).toContain('"${CHANT_AGENT_DRIFT:-0}" != "1"');
+    expect(doc["drift-app-agent-push"]!.script[0]).toContain("decision.json");
+  });
+
+  test("a runner group is refused", () => {
+    expect(() => gen({ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, runner: { group: "infra" } })).toThrow(/runner group/);
+  });
+});
+
+// #4619: a member's drift Op runs in the member's directory, and its artifact keeps the drift there.
+describe("the drift agent of a workspace member on GitLab", () => {
+  const out = generateGitlabOpPipeline([{ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, agent: { on: "drift", maxCostUsd: 4 } }], { member: { name: "app", dir: "stacks/app" } });
+  const doc = parseYAML(out.files[0]!.yaml) as unknown as Record<string, Job>;
+  const op = doc["app-drift-app"]!;
+  const agent = doc["app-drift-app-agent"]!;
+  const push = doc["app-drift-app-agent-push"]!;
+
+  test("the drift check runs in the member's directory and keeps the drift under it", () => {
+    expect(op.script[0]).toBe("cd stacks/app");
+    expect(op.artifacts?.paths).toEqual(["stacks/app/.chant/agent"]);
+    expect(op.artifacts?.reports).toEqual({ dotenv: "stacks/app/.chant/agent/drift.env" });
+  });
+
+  test("the agent and push jobs read the member's own drift output", () => {
+    expect(agent.script.some((l) => l.startsWith("cd "))).toBe(false);
+    expect(agent.script.find((l) => l.includes("agent prepare"))).toBe("chant agent prepare --forge gitlab --output stacks/app/.chant/agent");
+    expect(agent.script.at(-1)).toBe("chant agent run --forge gitlab --output stacks/app/.chant/agent");
+    expect(agent.artifacts?.paths).toEqual(["stacks/app/.chant/agent"]);
+    expect(push.script[0]).toContain("stacks/app/.chant/agent/decision.json");
+    expect(push.script.at(-1)).toBe("chant agent land --forge gitlab --output stacks/app/.chant/agent");
+  });
+
+  test("the money limit reaches both jobs and the file's header", () => {
+    expect(agent.variables?.CHANT_AGENT_MAX_COST_USD).toBe("4");
+    expect(push.variables?.CHANT_AGENT_MAX_COST_USD).toBe("4");
+    expect(out.files[0]!.yaml).toContain("and to $4 a day of recorded cost");
+  });
+});

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

@@ -1,21 +1,86 @@
 /**
- * `reviewAgent` on GitLab (#4326): refused by name. A merge request pipeline
- * hands every job the project's unprotected variables, so a review job there
- * cannot be kept apart from a token that writes.
+ * `reviewAgent` on GitLab (#4544): the review job runs in the merge request
+ * pipeline with no forge token and keeps its review as an artifact; the note
+ * job runs in a pipeline of the default branch, checks nothing out, and posts
+ * with the protected token.
  */
 
 import { describe, expect, test } from "vitest";
+import { FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { ComponentPipelineOptions, ScheduledOpSpec } from "@intentius/chant/lexicon";
 import { generateGitlabOpPipeline } from "./generate-op-pipeline";
 
+const spec: ScheduledOpSpec = { name: "pr-review", trigger: { kind: "pull_request" }, reviewAgent: true };
+
+function generated(specs: ScheduledOpSpec[] = [spec], options: ComponentPipelineOptions = {}) {
+  const out = generateGitlabOpPipeline(specs, options);
+  return { out, doc: parseYAML(out.files[0].yaml) as Record<string, Record<string, unknown>> };
+}
+
+const ruleText = (job: Record<string, unknown>): string => JSON.stringify(job.rules);
+const inMergeRequestPipeline = (job: Record<string, unknown>): boolean => ruleText(job).includes("merge_request_event");
+
 describe("generateGitlabOpPipeline: reviewAgent", () => {
-  test("is refused, naming the Op and the way out", () => {
-    expect(() => generateGitlabOpPipeline([{ name: "pr-review", trigger: { kind: "pull_request" }, reviewAgent: true }])).toThrow(
-      /Scheduled Op "pr-review" sets reviewAgent.*unprotected variables.*findingMode "comment".*GitHub or Forgejo/s,
-    );
+  test("emits the review job and its note job", () => {
+    const { out, doc } = generated();
+    expect(out.jobs.map((j) => j.jobName)).toEqual(["pr-review"]);
+    expect(Object.keys(doc)).toEqual(["stages", "pr-review", "pr-review-note"]);
+    expect(out.files[0].yaml).toContain('CHANT_REVIEW_NOTES="1"');
+    expect(out.files[0].yaml).toContain("protected, masked CI/CD variable");
+  });
+
+  test("the review job runs in the merge request pipeline, drops every forge token first and keeps the review as an artifact", () => {
+    const { doc } = generated();
+    const review = doc["pr-review"];
+    expect(inMergeRequestPipeline(review)).toBe(true);
+    const script = review.script as string[];
+    expect(script[0]).toBe(`unset ${FORGE_TOKEN_VARS.join(" ")}`);
+    expect(script).toContain("chant run pr-review");
+    expect(review.variables).toEqual({ CHANT_REVIEW_DIR: ".chant/review" });
+    expect(review.artifacts).toEqual({ paths: [".chant/review"], expire_in: "7 days" });
+  });
+
+  test("no job of the merge request pipeline holds a write token", () => {
+    const { doc } = generated([spec, { name: "lint", trigger: { kind: "pull_request" } }], { variables: { FOO: "bar" } });
+    const writeTokens = ["CHANT_FORGE_TOKEN", "CHANT_RUNNER_KEY", "GITLAB_TOKEN", "CHANT_GITLAB_TOKEN"];
+    for (const [name, job] of Object.entries(doc)) {
+      if (name === "stages" || name === "variables" || !inMergeRequestPipeline(job)) continue;
+      const text = JSON.stringify({ variables: job.variables ?? {}, script: (job.script as string[]).filter((l) => !l.startsWith("unset ")) });
+      for (const token of writeTokens) expect(text, `${name} ${token}`).not.toContain(token);
+    }
+    expect(Object.keys(doc.variables ?? {})).toEqual(["FOO"]);
+  });
+
+  test("the note job runs only in a pipeline of the default branch, checks nothing out and treats the artifact as data", () => {
+    const { doc } = generated([{ ...spec, trigger: { kind: "pull_request", branches: ["main", "release"] } }]);
+    const note = doc["pr-review-note"];
+    expect(inMergeRequestPipeline(note)).toBe(false);
+    expect(note.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE =~ /^(schedule|web|api|trigger)$/ && $CHANT_REVIEW_NOTES == "1" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]);
+    expect(note.variables).toEqual({ GIT_STRATEGY: "none" });
+    const script = (note.script as string[]).join("\n");
+    expect(script).toMatch(/npm install .*@intentius\/chant@\d+\.\d+\.\d+/);
+    expect(script).toContain("postOpenReviewNotes");
+    expect(script).toContain('const branches = ["main","release"]');
+    expect(script).toContain('job: "pr-review", artifactDir: ".chant/review", op: "pr-review"');
+    expect(script).not.toContain("chant run");
+  });
+
+  test("a workspace member's review keeps its artifact under the member's directory", () => {
+    const { doc } = generated([spec], { member: { name: "web", dir: "apps/web" } });
+    expect(doc["web-pr-review"].artifacts).toEqual({ paths: ["apps/web/.chant/review"], expire_in: "7 days" });
+    expect((doc["web-pr-review-note"].script as string[]).join("\n")).toContain('job: "web-pr-review", artifactDir: "apps/web/.chant/review"');
+  });
+
+  test("is refused on a trigger with no merge request, a posting finding-mode, or a write scope", () => {
+    expect(() => generateGitlabOpPipeline([{ ...spec, trigger: { kind: "push" } }])).toThrow(/sets reviewAgent.*trigger is "push"/s);
+    expect(() => generateGitlabOpPipeline([{ ...spec, findingMode: "comment" }])).toThrow(/findingMode "comment".*must be "report"/s);
+    expect(() => generateGitlabOpPipeline([{ ...spec, permissions: { "pull-requests": "write" } }])).toThrow(/"pull-requests: write"/);
   });
 
   test("an Op without it generates as before", () => {
     const out = generateGitlabOpPipeline([{ name: "pr-review", trigger: { kind: "pull_request" }, findingMode: "comment" }]);
     expect(out.jobs.map((j) => j.jobName)).toEqual(["pr-review"]);
+    expect(out.files[0].yaml).not.toContain("CHANT_REVIEW_NOTES");
   });
 });

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

@@ -103,6 +103,15 @@
  * internal and always wins at the job over a same-named spec entry, so a
  * caller cannot point the gate block somewhere the `artifacts:` declaration
  * beside it does not also point.
+ *
+ * `reviewAgent` (#4544) splits the review in two, as on GitHub and Forgejo,
+ * with GitLab's own shape (`./review-jobs.ts`). The review job runs in the
+ * merge request pipeline, unsets every forge token variable and keeps the
+ * review as its artifact. Its note job runs in a pipeline of the default
+ * branch that a schedule starts with `CHANT_REVIEW_NOTES` set to `1`, checks
+ * nothing out and posts each open merge request's review with the protected
+ * `CHANT_FORGE_TOKEN`. The header says to create that schedule and protect
+ * the token.
  */
 
 import {
@@ -114,6 +123,8 @@ import {
   gitlabIdTokens,
   gitlabRules,
   gitlabSetupScript,
+  gitlabTags,
+  assertRunnerLabels,
   nonEmpty,
   pushBranches,
 } from "@intentius/chant/ci-jobs";
@@ -129,6 +140,10 @@ import type {
 } from "@intentius/chant/lexicon";
 
 import { emitGitlabFile } from "./ci-jobs";
+import { assertReviewSplit, GITLAB_REVIEW_NOTES_VAR, gitlabReviewJobs, REVIEW_DIR, reviewNoteJobName } from "./review-jobs";
+import { AGENT_DIR, resolveAgentSpec } from "@intentius/chant/ci-agent";
+import { activeProductWords } from "@intentius/chant/ci-product-words";
+import { gitlabAgentHeader, gitlabAgentJobs, gitlabAgentPushJobName, gitlabDriftArtifacts, gitlabDriftRunLines } from "./agent-jobs";
 
 export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
 
@@ -202,24 +217,6 @@ function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: O
   );
 }
 
-/**
- * Refuse `reviewAgent` (#4326). The split posts the review from a second job
- * that holds the forge write token, and a GitLab merge request pipeline hands
- * every job the project's unprotected CI/CD variables, the review job's
- * included. A token protected enough to stay out of it is not available to a
- * job of that pipeline either, so the post has to start from a pipeline of
- * the default branch, which this generator does not build. The refusal names
- * the Op and the way out rather than emitting a review job that holds the token.
- */
-function assertNoReviewSplit(spec: ScheduledOpSpec): void {
-  if (!spec.reviewAgent) return;
-  throw new Error(
-    `Scheduled Op "${spec.name}" sets reviewAgent, which keeps the model's job free of the forge write token and posts the note from a second job. ` +
-      `A GitLab merge request pipeline hands every job the project's unprotected variables, so the gitlab generator does not build that split. ` +
-      `Drop reviewAgent and run the review with findingMode "comment" (the model command still runs with a cleared environment), or generate this Op for GitHub or Forgejo.`,
-  );
-}
-
 /**
  * The follow-up line an Op with an `environment` adds under its own header
  * line (#2257). The `environment:` key on the job binds it to the
@@ -303,20 +300,62 @@ export function generateGitlabOpPipeline(
 
   const opLines: string[] = [];
   let anyCron = false;
+  let anyReview = false;
+  // The note job of each split review (#4544), emitted after the Op jobs.
+  const noteJobs: string[] = [];
+  const words = activeProductWords();
 
   for (const spec of ops) {
     const subject = `Scheduled Op "${spec.name}"`;
+    // #4616: GitLab picks a runner by tags.
+    assertRunnerLabels(subject, "runner", spec.runner, "GitLab");
+    const tags = gitlabTags(spec.runner);
     const setupScript = gitlabSetupScript(subject, spec.setup);
+    // #4616: the comment agent is its own pair of jobs, in a pipeline of the default branch; the spec's trigger is not read.
+    if (spec.agent?.on === "comment") {
+      const settings = resolveAgentSpec(spec.name, spec.agent, words.product);
+      const jobName = jobPrefix + ciJobName(spec.name);
+      jobs.push({ jobName, op: spec.name, trigger: { kind: "pull_request" }, findingMode: "report" });
+      opLines.push(...gitlabAgentHeader(jobName, settings, spec.agent.tokenEnv));
+      const { agent, push } = gitlabAgentJobs({
+        jobName,
+        stage,
+        image,
+        settings,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        script: [...setupScript, ...beforeScript],
+        ...(spec.agent.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+      });
+      doc[jobName] = agent;
+      const pushName = gitlabAgentPushJobName(jobName);
+      doc[pushName] = push;
+      noteJobs.push(pushName);
+      continue;
+    }
     const idTokens = gitlabIdTokens(spec.name, spec.permissions);
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
-    assertNoReviewSplit(spec);
+    // A split review (#4544): the merge request pipeline runs the model with no forge token, and a pipeline of the default branch posts.
+    const split = spec.reviewAgent === true;
+    if (split) assertReviewSplit(spec.name, trigger, findingMode, spec.permissions);
     if (trigger.kind === "cron") anyCron = true;
+    const driftAgent = spec.agent?.on === "drift" ? resolveAgentSpec(spec.name, spec.agent, words.product) : undefined;
+    if (driftAgent && (split || trigger.kind === "push")) {
+      throw new Error(`${subject} sets a drift agent, which follows a drift check's run; give it a cron or pull_request trigger and no reviewAgent.`);
+    }
 
     const jobName = jobPrefix + ciJobName(spec.name);
     jobs.push({ jobName, op: spec.name, trigger, findingMode });
     opLines.push(headerLineFor(spec, trigger, jobName, findingMode));
+    if (split) {
+      anyReview = true;
+      opLines.push(
+        `#     reviewAgent: the review job holds no forge token and keeps its review as an artifact; ${reviewNoteJobName(jobName)} posts it` +
+          ` from a pipeline of the default branch started with ${GITLAB_REVIEW_NOTES_VAR}="1"`,
+      );
+    }
     if (spec.environment) {
       assertGitlabEnvironment(spec.name, spec.environment);
       opLines.push(environmentLine(spec.environment));
@@ -340,25 +379,70 @@ export function generateGitlabOpPipeline(
       ...(gated ? { [GATE_SUMMARY_VAR]: gateSummary } : {}),
     };
 
+    const rulesFor = changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules;
+    if (split) {
+      const { review, note } = gitlabReviewJobs({
+        name: spec.name,
+        jobName,
+        stage,
+        image,
+        rules: rulesFor,
+        script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+        ...(spec.variables ? { variables: spec.variables } : {}),
+        ...(idTokens ? { idTokens } : {}),
+        artifactDir: member ? memberRepoPath(member, REVIEW_DIR) : REVIEW_DIR,
+        ...(trigger.kind === "pull_request" && trigger.branches?.length ? { branches: trigger.branches } : {}),
+      });
+      doc[jobName] = { ...review, ...(tags ? { tags } : {}), ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) };
+      const noteName = reviewNoteJobName(jobName);
+      doc[noteName] = { ...note, ...(tags ? { tags } : {}) };
+      noteJobs.push(noteName);
+      continue;
+    }
+
+    const runLines = driftAgent ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
     doc[jobName] = {
       stage,
       image,
+      ...(tags ? { tags } : {}),
       // GitLab's stand-in for github's per-Op concurrency group: queue the
       // next run rather than cancel the current one.
       resource_group: jobName,
       ...(idTokens ? { id_tokens: idTokens } : {}),
       ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
       ...nonEmpty("variables", jobVariables),
-      rules: changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules,
-      script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+      rules: rulesFor,
+      script: [...cdLine, ...setupScript, ...beforeScript, ...runLines, ...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: [member ? memberRepoPath(member, gateSummary) : gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
-        : {}),
+        : driftAgent
+          ? { artifacts: gitlabDriftArtifacts(member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR) }
+          : {}),
     };
+    if (driftAgent) {
+      const name = `${jobName}-agent`;
+      opLines.push(...gitlabAgentHeader(name, driftAgent, spec.agent?.tokenEnv));
+      const { agent, push } = gitlabAgentJobs({
+        jobName: name,
+        stage,
+        image,
+        settings: driftAgent,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        script: [...setupScript, ...beforeScript],
+        ...(spec.agent?.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+        after: { job: jobName, rules: rulesFor },
+        // #4619: a member's drift Op left the drift under the member's directory.
+        ...(member ? { dir: memberRepoPath(member, AGENT_DIR) } : {}),
+      });
+      doc[name] = agent;
+      doc[gitlabAgentPushJobName(name)] = push;
+      noteJobs.push(name, gitlabAgentPushJobName(name));
+    }
   }
 
   const headerLines = [
@@ -375,10 +459,20 @@ export function generateGitlabOpPipeline(
       "# that job runs on that schedule.",
     );
   }
+  if (anyReview) {
+    headerLines.push(
+      "#",
+      "# A reviewAgent Op's note job posts from a pipeline of the default branch,",
+      `# never from the merge request's own. Create a Pipeline Schedule on the`,
+      `# default branch with ${GITLAB_REVIEW_NOTES_VAR}="1", and make CHANT_FORGE_TOKEN`,
+      "# (a token with the api scope) a protected, masked CI/CD variable so no",
+      "# merge request pipeline gets it.",
+    );
+  }
   headerLines.push("#", ...opLines);
 
   const yaml = emitGitlabFile(
-    [["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables] as const] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]] as const)],
+    [["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables] as const] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]] as const), ...noteJobs.map((name) => [name, doc[name]] as const)],
     headerLines,
   );
 

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

@@ -0,0 +1,55 @@
+/**
+ * An Op waves spec's `control` on GitLab (#4617): a control stage after the
+ * waves, the outcome added up without the token, and every other job
+ * dropping the control repo's token variables. Written for the ci-products
+ * session; run at epic-ready.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGitlabOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "stacks",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [
+    { name: "canary", runs: [{ target: "dev" }], gate: "never" },
+    { name: "rest", runs: [{ target: "a" }] },
+  ],
+  resume: { schedule: "*/10 * * * *" },
+  control: { repo: "gitlab.com/acme/control", op: "deploy", member: "network", tokenSecret: "PLYWOOD_CONTROL_TOKEN" },
+};
+
+const options = { specFile: "waves.json", bin: "npx --no-install plywood", words: { product: "plywood" } };
+
+describe("the control dispatch after the last wave on GitLab (#4617)", () => {
+  test("a control stage after the waves, needing the last wave's job", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/stages:\n\s+- wave-1-canary\n\s+- wave-2-rest\n\s+- control\n\s+- resume/);
+    expect(yaml).toMatch(/control-dispatch:\n\s+stage: control[\s\S]*needs:\n\s+- wave-2-rest\n/);
+  });
+
+  test("adds up the outcome in a subshell without the token, then sends it with the commit", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toContain("unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN\n      { :\n      } 1>&2\n      npx --no-install plywood run wave --spec waves.json --waves-outcome");
+    expect(yaml).toContain('export CHANT_CONTROL_OUTCOME="$outcome"');
+    expect(yaml).toContain('export CHANT_CONTROL_SHA="$CI_COMMIT_SHA"');
+    expect(yaml).toContain('CHANT_CONTROL_TOKEN="${PLYWOOD_CONTROL_TOKEN:-}"');
+    expect(yaml).toContain("--form 'token=<-'");
+    expect(yaml).toContain('--form "variables[CHANT_CONTROL_OUTCOME]=$outcome"');
+  });
+
+  test("every wave job and the resume job drop the control repo's token variables first", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/wave-1-canary:[\s\S]*script:\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN\n\s+- npx --no-install plywood run wave --spec waves.json --wave 1/);
+    expect(yaml).toMatch(/stacks-resume:[\s\S]*script:\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN/);
+  });
+
+  test("no control, no stage, no unset", () => {
+    const { control: _drop, ...plain } = spec;
+    const yaml = generateGitlabOpWavesPipeline(plain, options).files[0]!.yaml;
+    expect(yaml).not.toContain("control-dispatch");
+    expect(yaml).not.toContain("unset CHANT_CONTROL_TOKEN");
+  });
+});

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

@@ -129,4 +129,21 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     expect(JSON.stringify(doc["wave-1-prod-decide"])).not.toContain("apply\"");
     expect(JSON.stringify(doc["wave-1-prod-default"])).not.toContain("prod-apply");
   });
+
+  test("words.bin is the command in every job line: the waves, resume and the plans job (#4607)", () => {
+    const bin = "npx --no-install plywood";
+    const withBin = { ...spec, resume: { schedule: "*/10 * * * *" }, waves: spec.waves.map((w, i) => (i === spec.waves.length - 1 ? { ...w, approval: "pr-review" as const } : w)) };
+    const { files, jobs } = generateGitlabOpWavesPipeline(withBin, { specFile: "waves.json", bin });
+    expect(jobs.every((j) => j.command.slice(0, 3).join(" ") === bin)).toBe(true);
+    const yaml = files.map((f) => f.yaml).join("\n");
+    expect(yaml).toContain("- npx --no-install plywood run wave --spec waves.json --wave 1");
+    expect(yaml).toContain("npx --no-install plywood run resume --op migrations");
+    expect(yaml).toContain("npx --no-install plywood run wave --spec waves.json --record-plans");
+    expect(yaml).not.toMatch(/(^|\s)chant run (wave|resume)/m);
+  });
+
+  test("no bin keeps chant (#4607)", () => {
+    const { jobs } = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json" });
+    expect(jobs.every((j) => j.command[0] === "chant")).toBe(true);
+  });
 });