@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/ci-run.ts

@@ -53,7 +53,9 @@
  * report with its own token (`postPlanReport`, ../pr-post.ts). In place, a
  * generated job holds no token and its `plan-note` job posts; a job that
  * still holds one was generated before #4295, and the runner posts for it
- * with a warning to regenerate.
+ * with a warning to regenerate. Either way the note's overdue check (#4289)
+ * reads the scheduled Ops from a fresh checkout of `--base`, as the
+ * plan-note job reads them at the target branch's commit (#4328).
  *
  * Signing is opt-in (#4156). With no runner key the record is unsigned, and
  * a reader counts it with no signer. A key `.chant/trust.json` does not list
@@ -81,14 +83,16 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { PR_APPLY_RECORD, PR_ENV_POST_JOB, PR_ENV_REPORT_DIR, PR_LOOP_REPORT_DIR, prEnvJobs, prLoopJobs, prLoopSetup, PR_LOOP_IMAGE, type PrEnvJob, type PrLoopJob, type PrLoopPipelineOptions } from "../components/pr-pipeline";
 import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS, type CommitStatus, type ForgeKind, type PrForge } from "../pr-forge";
 import { holdsForgeToken, withoutForgeTokens } from "../ci-handover";
 import { postPlanReport } from "../pr-post";
-import { PR_APPLY_GATE } from "../pr-loop";
+import { overdueOpsAt } from "../op/schedule-overdue";
+import { PR_APPLY_GATE, type PrOverdue } from "../pr-loop";
 import type { CommandContext } from "../cli/registry";
 import { formatError, formatWarning } from "../cli/format";
 import { CHANT_CI_RUN_FORGE_ENV, CHANT_CI_RUN_ID_ENV, FORGE_RUN_ENV, resolveCiJob, type RunOrigin } from "../lifecycle/release-ledger";
@@ -738,7 +742,9 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   // A generated wave job's command, as prLoopWaveJobs writes it. #4161: a local job's command posts no status or note.
   const forgeCommand = req.noForge ? found.command.replace(` --forge ${req.forge}`, "") : found.command;
   const noStatus = req.local && !/ --no-status(?: |$)/.test(forgeCommand);
-  const command = `${forgeCommand}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${noStatus ? " --no-status" : ""}`;
+  // #4325: a record or apply on a routed branch is told the branch, as the forge's ref would tell it in a pipeline. `ci serve` has no such ref.
+  const branch = req.job !== "plan" && req.loop?.branch !== undefined && !/ --branch(?: |=)/.test(forgeCommand) ? ` --branch ${/^[A-Za-z0-9._\/=:@%+,-]+$/.test(req.loop.branch) ? req.loop.branch : `'${req.loop.branch.replace(/'/g, `'\\''`)}'`}` : "";
+  const command = `${forgeCommand}${branch}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${noStatus ? " --no-status" : ""}`;
   const job = { ...found, command, ...(req.wave !== undefined ? { wave: req.wave } : {}) };
   const own = ciJobEnv(job, {
     forge: req.forge,
@@ -759,7 +765,7 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const redact = ciRedactor(req.inPlace ? { ...longValues(jobEnv), ...own } : jobEnv, req.secrets);
   try {
     const ran = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
-    const posted = poster ? await postFromReport(req, poster, ran, { commit, ...(place.member ? { member: place.member } : {}) }) : [];
+    const posted = poster ? await postFromReport(req, poster, ran, { top, dir: place.dir, commit, ...(place.member ? { member: place.member } : {}) }) : [];
     const envPost = req.job === "env-up" ? await envPostAfterUp(req, { cwd, top, head: commit, place, jobs, hostEnv, ran }) : undefined;
     const withPost = envPost ? ("result" in envPost ? { ...ran, post: envPost.result } : { ...ran, warnings: [...ran.warnings, envPost.warning] }) : ran;
     const withPosts = posted.length > 0 ? { ...withPost, warnings: [...withPost.warnings, ...posted] } : withPost;
@@ -831,10 +837,11 @@ async function postFromReport(
   req: CiRunRequest,
   poster: NonNullable<ReturnType<typeof planPoster>>,
   ran: CiRunResult,
-  at: { commit: string; member?: string },
+  at: { top: string; dir: string; commit: string; member?: string },
 ): Promise<string[]> {
   if ("error" in poster) return [poster.error];
   const warnings = poster.warning ? [poster.warning] : [];
+  const checked: string[] = [];
   const dir = ran.report ?? resolve(req.cwd, req.output ?? PR_LOOP_REPORT_DIR);
   const posted = await postPlanReport({
     forge: poster.forge,
@@ -844,9 +851,62 @@ async function postFromReport(
     env: req.env,
     ...(at.member ? { member: at.member } : {}),
     result: ran.status === "ok" ? "success" : "failure",
+    // #4328: as pr-post does (#4289), with the Ops read at --base, never from the change's checkout.
+    overdue: () => overdueAtBase(req, { forge: poster.forge, top: at.top, dir: at.dir, ...(at.member ? { member: at.member } : {}), log: (line) => checked.push(line) }),
   });
   if (posted.refused) warnings.push(`the plan report was not posted: ${posted.refused}`);
-  return [...warnings, ...posted.warnings];
+  return [...warnings, ...checked, ...posted.warnings];
+}
+
+/**
+ * The overdue check for the plan's note (#4289, #4328), at `--base`, as the
+ * plan-note job's `pr-post` runs it at the target branch's commit. The Ops
+ * are read from a fresh checkout of the base outside the repository, never
+ * from the checkout the change's code ran in, in place or not. That checkout
+ * resolves packages from the `node_modules` the running chant is installed
+ * in ({@link chantNodeModules}), so an Op file's `@intentius/chant` is the
+ * chant running the job, not one the change installed. Without `--base`
+ * nothing is checked, and `log` says so.
+ */
+async function overdueAtBase(
+  req: CiRunRequest,
+  at: { forge: PrForge; top: string; dir: string; member?: string; log: (line: string) => void },
+): Promise<PrOverdue[]> {
+  if (!at.forge.scheduledRuns) return [];
+  if (!req.base) {
+    at.log("the scheduled Ops were not checked: the check reads them at the target branch's commit, so pass --base <sha>");
+    return [];
+  }
+  let checkout: { dir: string; remove(): void };
+  try {
+    checkout = freshCheckout(at.top, resolveJobCommit(at.top, req.base));
+  } catch (err) {
+    at.log(`the scheduled Ops were not checked: ${message(err)}`);
+    return [];
+  }
+  try {
+    const modules = chantNodeModules();
+    const link = join(checkout.dir, "node_modules");
+    if (modules && !existsSync(link)) symlinkSync(modules, link, "dir");
+    return await overdueOpsAt({ forge: at.forge, cwd: at.dir === "." ? checkout.dir : join(checkout.dir, at.dir), ...(at.member ? { member: at.member } : {}), log: at.log });
+  } finally {
+    checkout.remove();
+  }
+}
+
+/**
+ * The `node_modules` directory the running chant is installed in, or
+ * undefined when it runs from a source checkout, where chant's own packages
+ * resolve without one (../ts-loader.ts).
+ */
+export function chantNodeModules(from: string = fileURLToPath(import.meta.url)): string | undefined {
+  let dir = dirname(from);
+  for (;;) {
+    if (basename(dir) === "node_modules") return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
 }
 
 /**

package/src/workspace/ci-serve.test.ts

@@ -602,3 +602,98 @@ describe("ci serve runs fast-forwards only, and honours [skip ci] (#4122)", () =
     expect(ofType(events, "not-run")).toHaveLength(1);
   });
 });
+
+describe("ci serve follows ci.branches (#4325)", () => {
+  /** A forge with a head per branch, and the branches it was asked about. */
+  function branchForge(heads: Record<string, string>): CiServeForge & { heads: Record<string, string>; polled: string[] } {
+    const f = {
+      heads,
+      polled: [] as string[],
+      async pullRequestFor() {
+        return null;
+      },
+      async openPullRequests(base: string) {
+        f.polled.push(base);
+        return [];
+      },
+      async branchHead(branch: string) {
+        return f.heads[branch];
+      },
+    };
+    return f;
+  }
+
+  /** The workspace with `ci.branches` routing `app` to `release`, and a `release` branch on the forge. */
+  function routed(globs: string[] = ["app"]): ReturnType<typeof workspace> & { release: string } {
+    const w = workspace();
+    writeFiles(w.root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { branches: { release: globs } } }) });
+    commit(w.root, "app/route.txt", "route app to release");
+    git(w.root, "push", "-q", "origin", "main");
+    git(w.root, "checkout", "-q", "-b", "release");
+    const release = commit(w.root, "app/rel.txt");
+    git(w.root, "push", "-q", "origin", "release");
+    git(w.root, "checkout", "-q", "main");
+    return { ...w, main: git(w.root, "rev-parse", "main"), release };
+  }
+
+  test("a routed member polls its route alone, and its record job gets --branch", async () => {
+    const { root, app, main, release } = routed();
+    const forge = branchForge({ main, release });
+    const { opts, events } = serve(app, forge);
+    await ciServePass(opts);
+    expect(forge.polled).toEqual(["release"]);
+    expect(ofType(events, "baseline")).toEqual([{ type: "baseline", commit: release }]);
+
+    git(root, "checkout", "-q", "release");
+    const next = commit(root, "app/rel2.txt");
+    git(root, "push", "-q", "origin", "release");
+    git(root, "checkout", "-q", "main");
+    forge.heads.release = next;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "record", commit: next, base: release, status: "ok" })]);
+    const argv = argsOf(pass.jobs[0]!.report!, "pr-record");
+    expect(argv[argv.indexOf("--branch") + 1]).toBe("release");
+    // A push to main is not this member's.
+    forge.heads.main = "0".repeat(40);
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+  });
+
+  test("a member no glob matches polls main and passes no --branch", async () => {
+    const { root, app, main } = routed(["other-*"]);
+    const forge = branchForge({ main });
+    const { opts } = serve(app, forge);
+    await ciServePass(opts);
+    expect(forge.polled).toEqual(["main"]);
+    const merged = commit(root, "app/merged.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.heads.main = merged;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "record", commit: merged, base: main })]);
+    expect(argsOf(pass.jobs[0]!.report!, "pr-record")).not.toContain("--branch");
+  });
+
+  test("the workspace root polls main and each routed branch, each from its own head", async () => {
+    const { root, main, release } = routed();
+    const forge = branchForge({ main, release });
+    const { opts } = serve(root, forge);
+    await ciServePass(opts);
+    expect(forge.polled).toEqual(["main", "release"]);
+    git(root, "checkout", "-q", "release");
+    const next = commit(root, "app/rel2.txt");
+    git(root, "push", "-q", "origin", "release");
+    git(root, "checkout", "-q", "main");
+    forge.heads.release = next;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "record", commit: next, base: release })]);
+    const state = readCiServeState(join(opts.stateDir!, `${prApplyGroup("prod")}.json`), { forge: "forgejo", repo: "demo/estate", env: "prod", branch: "main" });
+    expect(state.target).toBe(main);
+    expect(state.targets).toEqual({ release: next });
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+  });
+
+  test("a --branch that disagrees with the route is refused", async () => {
+    const { app, main, release } = routed();
+    const { opts } = serve(app, branchForge({ main, release }), { job: { loop: { branch: "main" } } });
+    await expect(ciServePass(opts)).rejects.toThrow(/routes member app to release/);
+  });
+});

package/src/workspace/ci-serve.ts

@@ -59,6 +59,11 @@
  *   contains the other. Each is a warning. A local branch ahead of the
  *   forge's keeps its facts, and the job's push sends them. Nothing here
  *   pushes the ledger.
+ * - Routed branches (#4325). `ci.branches` decides the branches one serve
+ *   polls: a routed member's route alone, an unrouted member's `--branch`
+ *   (default `main`), and at the workspace root `main` and each routed
+ *   branch. Jobs on a routed branch get `--branch`. The state file keeps a
+ *   head per branch (`target`, then `targets`).
  *
  * - Land branches (#4168 4.4). With `land`, each `chant/land/<name>` branch
  *   pushed to the remote is a change asking to land without a pull request.
@@ -104,6 +109,7 @@ import { CI_JOB_OPS, ciJobPlace, ciLoopOptions, ciSecretsOf, ciRun, ciStatusFrom
 import { CiGreenError, ciTick, judgePreMerge, lastGreen, RUNNER_KEY_ENV, signedRunsRequired, type CommitVerdict } from "./ci-green";
 import { gitTop } from "./tree";
 import { readDeclaration } from "./declaration";
+import { servedBranches } from "./ci-branches";
 import { locateWorkspace } from "./which-chant";
 import { ciServeRunnerKey, formatRunnerKeySetup, setupRunnerKey } from "./ci-runner-key";
 
@@ -124,8 +130,8 @@ export interface CiServeForge {
  * apply of the newest green commit (#4168 step 9).
  */
 export type CiServeTrigger =
-  | { job: "plan"; commit: string; base: string; pr: number; rerun?: boolean }
-  | { job: "apply" | "record"; commit: string; base: string; rerun?: boolean };
+  | { job: "plan"; commit: string; base: string; pr: number; rerun?: boolean; branch?: string }
+  | { job: "apply" | "record"; commit: string; base: string; rerun?: boolean; branch?: string };
 
 /**
  * The `git` forge kind (#4016 gap 6): the branch head from `git ls-remote`
@@ -193,6 +199,8 @@ export interface CiServeState {
   member?: string;
   /** The target branch's head the last apply was measured to, or the last head seen and not applied. */
   target?: string;
+  /** The same for each further branch `ci.branches` routes (#4325), by branch. `target` is the first served branch's. */
+  targets?: Record<string, string>;
   jobs: Record<string, CiServeJobState>;
   /** Plans seen and not run, by state key, with why (#4122). */
   skipped?: Record<string, "skip-ci">;
@@ -381,7 +389,12 @@ export function defaultCiServeStateDir(cwd: string): string {
 interface ServePlace {
   top: string;
   member?: string;
+  /** The first branch served: the one the state file's `target` follows. */
   branch: string;
+  /** Every branch served (#4325), `branch` first: a routed member's route, or at the workspace root the default and each routed branch. */
+  branches: string[];
+  /** The served branches a job is told with `--branch`: the ones `ci.branches` names. */
+  routed: string[];
   group: string;
   stateDir: string;
   stateFile: string;
@@ -394,7 +407,21 @@ function servePlace(opts: CiServeOptions): ServePlace {
   const { member } = ciJobPlace(cwd, top);
   const group = prApplyGroup(opts.env, member);
   const stateDir = opts.stateDir ? resolve(cwd, opts.stateDir) : defaultCiServeStateDir(cwd);
-  return { top, ...(member ? { member } : {}), branch: opts.job?.loop?.branch ?? "main", group, stateDir, stateFile: join(stateDir, `${group}.json`) };
+  // #4325: ci.branches decides which branches this serve polls. A workspace that can't be read routes nothing.
+  let routes: Record<string, string[]> | undefined;
+  try {
+    routes = readDeclaration(locateWorkspace(cwd).tree).ci?.branches;
+  } catch {
+    routes = undefined;
+  }
+  const named = opts.job?.loop?.branch;
+  let served: ReturnType<typeof servedBranches>;
+  try {
+    served = servedBranches(routes, member, named ?? "main", named !== undefined);
+  } catch (err) {
+    throw new CiRunError(message(err));
+  }
+  return { top, ...(member ? { member } : {}), branch: served.served[0]!, branches: served.served, routed: served.routed, group, stateDir, stateFile: join(stateDir, `${group}.json`) };
 }
 
 /** The state file, or a new one. */
@@ -439,73 +466,81 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
   };
   const triggers: CiServeTrigger[] = [];
   const events: CiServeEvent[] = [];
-  const [head, prs] = await Promise.all([opts.client.branchHead(place.branch), opts.client.openPullRequests(place.branch)]);
   // #4168: a new target commit is recorded. With applyOnMerge the newest green commit is applied, below.
   const onMerge = "record" as const;
+  const authors = opts.authors?.length ? new Set(opts.authors.map((a) => a.toLowerCase())) : undefined;
 
-  if (head === undefined) {
-    events.push({ type: "no-branch", branch: place.branch });
-  } else if (state.target === undefined) {
-    // What the branch held before this runner watched it was applied by whatever ran then.
-    update((s) => {
-      s.target = head;
-    });
-    events.push({ type: "baseline", commit: head });
-  } else if (head !== state.target) {
-    const from = state.target;
-    const move = targetMove(place.top, place.branch, from, head);
-    const entry = state.jobs[ciServeKey({ job: onMerge, commit: head })];
-    if (move === "unknown") {
-      events.push({ type: "error", message: `${place.branch} is at ${head.slice(0, 12)} on the forge, and that commit could not be fetched; the next poll tries again` });
-    } else if (move === "other" || (!entry && skipsCi(place.top, head))) {
-      // #4122: a move that is not a fast-forward, or a head that asks for no run, is seen and not applied.
-      update((s) => {
-        s.target = head;
-      });
-      events.push({ type: "not-run", job: onMerge, commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch: place.branch, from } : {}) });
-    } else if (!entry) triggers.push({ job: onMerge, commit: head, base: from });
-    else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true });
-  } else {
-    const key = ciServeKey({ job: onMerge, commit: head });
-    const entry = state.jobs[key];
-    if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true });
-  }
+  // #4325: each served branch is polled on its own, with its own head to measure moves from.
+  for (const branch of place.branches) {
+    const [head, prs] = await Promise.all([opts.client.branchHead(branch), opts.client.openPullRequests(branch)]);
+    const first = branch === place.branch;
+    const target = first ? state.target : state.targets?.[branch];
+    const setTarget = (s: CiServeState, sha: string): void => {
+      if (first) s.target = sha;
+      else s.targets = { ...s.targets, [branch]: sha };
+    };
+    // A job on a routed branch is told which, so its apply routes members as the pushed branch does.
+    const routed = place.routed.includes(branch) ? { branch } : {};
 
-  if (opts.applyOnMerge && head !== undefined) {
-    const green = newestGreen(place.top, opts.cwd, place.branch);
-    if (green) {
-      const key = ciServeKey({ job: "apply", commit: green });
+    if (head === undefined) {
+      events.push({ type: "no-branch", branch });
+    } else if (target === undefined) {
+      // What the branch held before this runner watched it was applied by whatever ran then.
+      update((s) => setTarget(s, head));
+      events.push({ type: "baseline", commit: head });
+    } else if (head !== target) {
+      const from = target;
+      const move = targetMove(place.top, branch, from, head);
+      const entry = state.jobs[ciServeKey({ job: onMerge, commit: head })];
+      if (move === "unknown") {
+        events.push({ type: "error", message: `${branch} is at ${head.slice(0, 12)} on the forge, and that commit could not be fetched; the next poll tries again` });
+      } else if (move === "other" || (!entry && skipsCi(place.top, head))) {
+        // #4122: a move that is not a fast-forward, or a head that asks for no run, is seen and not applied.
+        update((s) => setTarget(s, head));
+        events.push({ type: "not-run", job: onMerge, commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch, from } : {}) });
+      } else if (!entry) triggers.push({ job: onMerge, commit: head, base: from, ...routed });
+      else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true, ...routed });
+    } else {
+      const key = ciServeKey({ job: onMerge, commit: head });
       const entry = state.jobs[key];
-      if (!entry) triggers.push({ job: "apply", commit: green, base: green });
-      else if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "apply", commit: green, base: entry.base, rerun: true });
+      if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true, ...routed });
     }
-  }
 
-  const authors = opts.authors?.length ? new Set(opts.authors.map((a) => a.toLowerCase())) : undefined;
-  for (const pr of prs) {
-    if (pr.fork) {
-      events.push({ type: "skipped", pr: pr.number, reason: "fork" });
-      continue;
-    }
-    if (authors && !authors.has((pr.author ?? "").toLowerCase())) {
-      events.push({ type: "skipped", pr: pr.number, reason: "author", ...(pr.author ? { author: pr.author } : {}) });
-      continue;
+    if (opts.applyOnMerge && head !== undefined) {
+      const green = newestGreen(place.top, opts.cwd, branch, place.routed.includes(branch));
+      if (green) {
+        const key = ciServeKey({ job: "apply", commit: green });
+        const entry = state.jobs[key];
+        if (!entry) triggers.push({ job: "apply", commit: green, base: green, ...routed });
+        else if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "apply", commit: green, base: entry.base, rerun: true, ...routed });
+      }
     }
-    const key = ciServeKey({ job: "plan", commit: pr.headSha, pr: pr.number });
-    const entry = state.jobs[key];
-    const base = pr.baseSha ?? head;
-    if (!base || state.skipped?.[key]) continue;
-    if (!entry) {
-      // #4122: a head whose message asks for no run is seen and not planned.
-      if (gitStatus(place.top, ["cat-file", "-e", `${pr.headSha}^{commit}`]).code !== 0) tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", `refs/pull/${pr.number}/head`]);
-      if (skipsCi(place.top, pr.headSha)) {
-        update((s) => {
-          s.skipped = { ...s.skipped, [key]: "skip-ci" };
-        });
-        events.push({ type: "not-run", job: "plan", commit: pr.headSha, pr: pr.number, reason: "skip-ci" });
-      } else triggers.push({ job: "plan", commit: pr.headSha, base, pr: pr.number });
+
+    for (const pr of prs) {
+      if (pr.fork) {
+        events.push({ type: "skipped", pr: pr.number, reason: "fork" });
+        continue;
+      }
+      if (authors && !authors.has((pr.author ?? "").toLowerCase())) {
+        events.push({ type: "skipped", pr: pr.number, reason: "author", ...(pr.author ? { author: pr.author } : {}) });
+        continue;
+      }
+      const key = ciServeKey({ job: "plan", commit: pr.headSha, pr: pr.number });
+      const entry = state.jobs[key];
+      const base = pr.baseSha ?? head;
+      if (!base || state.skipped?.[key]) continue;
+      if (!entry) {
+        // #4122: a head whose message asks for no run is seen and not planned.
+        if (gitStatus(place.top, ["cat-file", "-e", `${pr.headSha}^{commit}`]).code !== 0) tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", `refs/pull/${pr.number}/head`]);
+        if (skipsCi(place.top, pr.headSha)) {
+          update((s) => {
+            s.skipped = { ...s.skipped, [key]: "skip-ci" };
+          });
+          events.push({ type: "not-run", job: "plan", commit: pr.headSha, pr: pr.number, reason: "skip-ci" });
+        } else triggers.push({ job: "plan", commit: pr.headSha, base, pr: pr.number, ...routed });
+      }
+      else if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "plan", commit: pr.headSha, base: entry.base, pr: pr.number, rerun: true, ...routed });
     }
-    else if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "plan", commit: pr.headSha, base: entry.base, pr: pr.number, rerun: true });
   }
   return { triggers, events };
 }
@@ -581,7 +616,10 @@ export async function ciServeSchedule(opts: CiServeOptions, triggers: readonly C
     const entry: CiServeJobState = { job: t.job, commit: t.commit, base: t.base, ...pr, status: "running", runId, attempts: attempt, startedAt: now().toISOString() };
     update((s) => {
       s.jobs[key] = entry;
-      if (t.job === "record" && !t.rerun) s.target = t.commit;
+      if (t.job === "record" && !t.rerun) {
+        if (t.branch === undefined || t.branch === place.branch) s.target = t.commit;
+        else s.targets = { ...s.targets, [t.branch]: t.commit };
+      }
     });
     emit({ type: "started", job: t.job, commit: t.commit, ...pr, base: t.base, runId, attempt, ...(resume && existsSync(resume) ? { resume } : {}) });
 
@@ -621,13 +659,15 @@ async function runJob(
   let merged: number | undefined;
   try {
     // The pull request's head is on the forge's refs/pull/<n>/head, the target's on the branch.
-    tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", t.job === "plan" ? `refs/pull/${t.pr}/head` : place.branch]);
+    tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", t.job === "plan" ? `refs/pull/${t.pr}/head` : (t.branch ?? place.branch)]);
     const hostEnv = { ...(opts.job?.hostEnv ?? process.env), GITHUB_REPOSITORY: opts.repo };
     // An apply is for a merge: pass the pull request whose merge commit it is, so the commit status link and the run index use `<pr>/<commit>`. None found, or a forge that errs, is today's behaviour.
     if (t.job === "record" && opts.client.pullRequestFor) merged = (await opts.client.pullRequestFor(t.commit).catch(() => null)) ?? undefined;
     const run = opts.run ?? ciRun;
     const r = await run({
       ...opts.job,
+      // #4325: a job on a routed branch is told the branch, so it routes members as a push to it does.
+      ...(t.branch !== undefined ? { loop: { ...opts.job?.loop, branch: t.branch } } : {}),
       hostEnv,
       cwd: opts.cwd,
       job: t.job,
@@ -656,10 +696,11 @@ async function runJob(
  * fetching the ci tags, or undefined when none is green or the workspace
  * declares no `ci.green`.
  */
-function newestGreen(top: string, cwd: string, branch: string): string | undefined {
+function newestGreen(top: string, cwd: string, branch: string, routed = false): string | undefined {
   tryGit(top, ["fetch", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`, "+refs/tags/ci/*:refs/tags/ci/*"]);
   try {
-    const doc = lastGreen({ cwd });
+    // #4325: a routed branch has its own verdict, and none when ci.green does not name it.
+    const doc = lastGreen({ cwd, ...(routed ? { branch } : {}) });
     return "commit" in doc && doc.commit ? doc.commit.sha : undefined;
   } catch {
     return undefined;

package/src/workspace/component-environments.test.ts

@@ -14,9 +14,12 @@ import Ajv2020 from "ajv/dist/2020";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { computeComponentGraph } from "../components/cli-support";
 import componentSchema from "../components/component.schema.json";
+import { ChantConfigSchema, environmentExecutor } from "../config";
 import { componentEnvironments, memberEnvironments, type EnvironmentReason } from "./environments";
 import type { MemberRuntimes } from "./runtimes";
 
+const NO_EXECUTOR = { forge: null, workflow: null, reason: { code: "executor-none-declared", message: expect.any(String) } };
+
 const runtimes = (environments: MemberRuntimes["environments"], lexicons: string[] = []): MemberRuntimes => ({ lexicons, default: "local", reasons: [], environments });
 
 const SITES = [
@@ -68,13 +71,14 @@ describe("graph --composites lists each environment with the component's site (#
     const member = memberEnvironments(runtimes(["prod", "fly"], ["fly"]), { envs: [], reason: null });
     const envs = componentEnvironments("app", member, "local", SITES, ["fly"]);
     expect(envs).toEqual([
-      { name: "local", default: true, source: "builtin", site: null, command: "chant run --components app" },
-      { name: "prod", default: false, source: "config", site: { runtime: "local", url: null, domain: null, lifecycle: null }, command: "chant run --components app --env prod" },
+      { name: "local", default: true, source: "builtin", site: null, executor: NO_EXECUTOR, command: "chant run --components app" },
+      { name: "prod", default: false, source: "config", site: { runtime: "local", url: null, domain: null, lifecycle: null }, executor: NO_EXECUTOR, command: "chant run --components app --env prod" },
       {
         name: "fly",
         default: false,
         source: "config",
         site: { runtime: "fly", url: "https://shop.fly.dev", domain: "shop.example.com", lifecycle: "origin" },
+        executor: NO_EXECUTOR,
         command: "chant run --components app --on fly --env fly",
       },
     ]);
@@ -103,3 +107,22 @@ describe("graph --composites lists each environment with the component's site (#
     expect(envs.find((e) => e.name === "pr-7")).toMatchObject({ source: "component", site: { url: "https://pr-7.example.com" } });
   });
 });
+
+describe("an environment's executor in chant.config.ts (#4402)", () => {
+  const prod = { name: "prod", executor: { forge: "github" as const, workflow: "deploy-prod.yml" } };
+
+  test("is optional on an environment entry, and refuses an unknown forge, an empty workflow and a stray field", () => {
+    expect(ChantConfigSchema.safeParse({ environments: ["staging", prod] }).success).toBe(true);
+    expect(ChantConfigSchema.safeParse({ environments: [{ name: "prod", executor: { forge: "jenkins", workflow: "x.yml" } }] }).success).toBe(false);
+    expect(ChantConfigSchema.safeParse({ environments: [{ name: "prod", executor: { forge: "github", workflow: "" } }] }).success).toBe(false);
+    expect(ChantConfigSchema.safeParse({ environments: [{ name: "prod", executor: { forge: "github", workflow: "x.yml", ref: "main" } }] }).success).toBe(false);
+  });
+
+  test("resolves a literal entry before a pattern, and a literal without one doesn't take the pattern's", () => {
+    const envs = [prod, "pr-special", { name: "pr-*", executor: { forge: "gitlab" as const, workflow: ".gitlab-ci.yml" } }];
+    expect(environmentExecutor(envs, "prod")).toEqual(prod.executor);
+    expect(environmentExecutor(envs, "pr-7")).toEqual({ forge: "gitlab", workflow: ".gitlab-ci.yml" });
+    expect(environmentExecutor(envs, "pr-special")).toBeUndefined();
+    expect(environmentExecutor(envs, "staging")).toBeUndefined();
+  });
+});

package/src/workspace/compose-graph.ts

@@ -100,6 +100,12 @@ export interface ComposedMember {
    * the outer `nodes` with `outer/inner/id` ids.
    */
   nested?: NestedWorkspace;
+  /**
+   * For a member of kind `repo` (#3168): the repository and pinned revision it
+   * names, and `read`, the repo identity the other repository's own graph
+   * document gave, or null. Its nodes fold in as a nested workspace's do.
+   */
+  repo?: { url: string; rev: string; workspace: string; read: string | null };
   /**
    * The factory and listing the member's box block declares (#3146, ws-077),
    * read from the declaration at the revision read. Set by
@@ -181,7 +187,8 @@ export type ComposedDangling = IRDanglingRef & { member: string; nested?: string
 
 export interface WorkspaceGraph {
   version: number;
-  workspace: { name: string; root: string };
+  /** `repo` (#3168): the repository the document came from, its origin URL redacted, or null; absent from a chant before it. */
+  workspace: { name: string; root: string; repo?: string | null };
   members: ComposedMember[];
   nodes: ComposedNode[];
   edges: ComposedEdge[];
@@ -335,7 +342,7 @@ function sorted(rec: Record<string, string[]>): Record<string, string[]> {
  * `read` holds the links each member's kind reader found in its files (#3932).
  */
 export function composeWorkspaceGraph(
-  workspace: { name: string; root: string },
+  workspace: { name: string; root: string; repo?: string | null },
   inputs: ComposeInput[],
   links?: { declaration: Declaration; kinds?: KindRegistry; read?: ReadonlyMap<string, KindLinkRead> },
 ): WorkspaceGraph {

package/src/workspace/composites.schema.json

@@ -607,6 +607,28 @@
             }
           ]
         },
+        "executor": {
+          "description": "The forge and committed workflow that deploys this environment, as the member's chant.config.ts declares on the environment's entry (#4402): a literal entry before a pattern. forge and workflow are null when none is declared, and reason then says why. Never derived from a generated workflow's name. Added by chant 0.124.47; a document from an older chant has no executor.",
+          "type": "object",
+          "required": ["forge", "workflow", "reason"],
+          "properties": {
+            "forge": { "enum": ["github", "gitlab", "forgejo", null] },
+            "workflow": { "type": ["string", "null"], "description": "The workflow file the forge runs, such as deploy-prod.yml under .github/workflows/, or .gitlab-ci.yml." },
+            "reason": {
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["code", "message"],
+                  "properties": {
+                    "code": { "enum": ["executor-none-declared", "executor-config-unreadable"] },
+                    "message": { "type": "string" }
+                  }
+                }
+              ]
+            }
+          }
+        },
         "command": {
           "type": "string",
           "description": "The command that deploys the component to this environment on its default runtime, run in the member's directory: chant run --components <name>, with --on <runtime> when the default runtime isn't local, and --env <env> for any environment but the default."