@intentius/chant 0.124.46 → 0.124.49

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."

package/src/workspace/composites.test.ts

@@ -17,6 +17,7 @@ import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import {
   COMPOSITES_CONTRACT_VERSION,
   COMPOSITES_ENVIRONMENT_REASON_CODES,
+  COMPOSITES_EXECUTOR_REASON_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_OUTPUT_SCHEMA_ID,
   COMPOSITES_REASON_CODES,
@@ -30,6 +31,8 @@ import {
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import schema from "./composites.schema.json";
 
+const NO_EXECUTOR = { forge: null, workflow: null, reason: { code: "executor-none-declared", message: expect.any(String) } };
+
 afterAll(cleanScratch);
 
 const { expectValid } = contract(schema);
@@ -61,7 +64,7 @@ const componentIr = (components: { name: string; composites?: string[]; archetyp
 const local = (name: string) => ({ name: "local", lexicon: null, default: true, command: `chant run --components ${name}` });
 
 /** The default environment, named by nothing but chant itself. */
-const localEnv = (name: string) => ({ name: "local", default: true, source: "builtin", site: null, command: `chant run --components ${name}` });
+const localEnv = (name: string) => ({ name: "local", default: true, source: "builtin", site: null, executor: NO_EXECUTOR, command: `chant run --components ${name}` });
 
 /**
  * app declares three instances and exports ImageUri; delivery links to it and
@@ -117,6 +120,7 @@ describe("composites output schema", () => {
     expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_RUN_REASON_CODES]);
     expect(schema.$defs.member.properties.runtimeReasons.items.properties.code.enum).toEqual([...COMPOSITES_RUNTIME_REASON_CODES]);
     expect(schema.$defs.member.properties.environmentReasons.items.properties.code.enum).toEqual([...COMPOSITES_ENVIRONMENT_REASON_CODES]);
+    expect(schema.$defs.environment.properties.executor.properties.reason.oneOf[1].properties!.code.enum).toEqual([...COMPOSITES_EXECUTOR_REASON_CODES]);
   });
 });
 
@@ -381,11 +385,11 @@ describe("the environments each component may deploy to (#2695)", () => {
     const g = result((await workspaceComposites({ cwd: declared() })).doc);
     expectValid(g);
     expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments).toEqual([
-      { name: "local", default: true, source: "builtin", site: null, command: "chant run --components queue-runner" },
-      { name: "staging", default: false, source: "config", site: null, command: "chant run --components queue-runner --env staging" },
-      { name: "prod", default: false, source: "config", site: null, command: "chant run --components queue-runner --env prod" },
+      { name: "local", default: true, source: "builtin", site: null, executor: NO_EXECUTOR, command: "chant run --components queue-runner" },
+      { name: "staging", default: false, source: "config", site: null, executor: NO_EXECUTOR, command: "chant run --components queue-runner --env staging" },
+      { name: "prod", default: false, source: "config", site: null, executor: NO_EXECUTOR, command: "chant run --components queue-runner --env prod" },
       // The pattern pr-* is no environment by itself, and it covers the ledger's pr-42.
-      { name: "pr-42", default: false, source: "ledger", site: null, command: "chant run --components queue-runner --env pr-42" },
+      { name: "pr-42", default: false, source: "ledger", site: null, executor: NO_EXECUTOR, command: "chant run --components queue-runner --env pr-42" },
     ]);
     const jobs = g.members.find((m) => m.name === "jobs")!;
     expect(jobs.environmentReasons).toEqual([{ code: "environments-ledger-undeclared", message: expect.stringContaining("retired") }]);
@@ -397,7 +401,7 @@ describe("the environments each component may deploy to (#2695)", () => {
     // delivery has no _members/delivery, so the flat staging ledger is its; its config declares nothing, so anything goes.
     expect(g.components.find((c) => c.id === "delivery/edge")!.environments).toEqual([
       localEnv("edge"),
-      { name: "staging", default: false, source: "ledger", site: null, command: "chant run --components edge --env staging" },
+      { name: "staging", default: false, source: "ledger", site: null, executor: NO_EXECUTOR, command: "chant run --components edge --env staging" },
     ]);
     expect(g.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
     expect(g.members.find((m) => m.name === "docs")!.environmentReasons).toEqual([]);
@@ -409,8 +413,8 @@ describe("the environments each component may deploy to (#2695)", () => {
     const g = result((await workspaceComposites({ cwd: root })).doc);
     expectValid(g);
     expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments).toEqual([
-      { name: "local", default: true, source: "config", site: null, command: "chant run --components queue-runner" },
-      { name: "prod", default: false, source: "config", site: null, command: "chant run --components queue-runner --env prod" },
+      { name: "local", default: true, source: "config", site: null, executor: NO_EXECUTOR, command: "chant run --components queue-runner" },
+      { name: "prod", default: false, source: "config", site: null, executor: NO_EXECUTOR, command: "chant run --components queue-runner --env prod" },
     ]);
     expect(g.members.find((m) => m.name === "jobs")!.environmentReasons).toEqual([]);
   });
@@ -445,4 +449,31 @@ describe("the environments each component may deploy to (#2695)", () => {
     expect(g.members.find((m) => m.name === "jobs")!.environmentReasons).toEqual([{ code: "environments-ledger-unreadable", message: "boom" }]);
     expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments.map((e) => e.name)).toEqual(["local", "prod"]);
   });
+
+  test("each environment names the forge workflow the config declares for it, a literal before a pattern (#4402)", async () => {
+    const root = declared();
+    writeFileSync(
+      join(root, "jobs", "chant.config.ts"),
+      'export default { environments: ["staging", { name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }, { name: "pr-*", executor: { forge: "forgejo", workflow: "preview.yml" } }] };\n',
+    );
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    const executors = Object.fromEntries(g.components.find((c) => c.id === "jobs/queue-runner")!.environments.map((e) => [e.name, e.executor]));
+    expect(executors).toEqual({
+      local: NO_EXECUTOR,
+      staging: NO_EXECUTOR,
+      prod: { forge: "github", workflow: "deploy-prod.yml", reason: null },
+      "pr-42": { forge: "forgejo", workflow: "preview.yml", reason: null },
+    });
+  });
+
+  test("a config that can't be read says no executor is known (#4402)", async () => {
+    const root = declared();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'throw new Error("no config here");\nexport default {};\n');
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    for (const e of g.components.find((c) => c.id === "jobs/queue-runner")!.environments) {
+      expect(e.executor).toEqual({ forge: null, workflow: null, reason: { code: "executor-config-unreadable", message: expect.stringContaining(e.name) } });
+    }
+  });
 });

package/src/workspace/composites.ts

@@ -36,7 +36,8 @@
  * And each component lists the environments it may deploy to (#2695,
  * `environments.ts`): `local`, the environments its member's config declares,
  * and those with a release in the member's ledger on `chant/lifecycle`, with
- * the command line for each.
+ * the command line for each, and the forge workflow that deploys each one
+ * when the member's config names it (#4402).
  */
 
 import { formatError } from "../cli/format";
@@ -50,7 +51,7 @@ import { emitDocument, type UnitResult } from "./member-commands";
 import { readerVersion, WORKSPACE_ERROR_CODES, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import type { ComponentEnvironmentDeclaration } from "../components/component";
-import { componentEnvironments, ENVIRONMENT_REASON_CODES, memberEnvironments, readLedgerEnvironments, type ComponentEnvironment, type EnvironmentReason, type LedgerEnvironmentReader, type MemberEnvironments } from "./environments";
+import { componentEnvironments, ENVIRONMENT_REASON_CODES, EXECUTOR_REASON_CODES, memberEnvironments, readLedgerEnvironments, type ComponentEnvironment, type EnvironmentReason, type LedgerEnvironmentReader, type MemberEnvironments } from "./environments";
 import { componentRuntimes, readRuntimesIn, RUNTIME_REASON_CODES, type ComponentRuntime, type MemberRuntimes, type PluginLoader, type RuntimeReason } from "./runtimes";
 
 /** `$id` of the JSON Schema for the document, shipped beside this file. */
@@ -83,6 +84,9 @@ export const COMPOSITES_RUNTIME_REASON_CODES = RUNTIME_REASON_CODES;
 /** Why a member's environments are only `local`, or leave out one its ledger has (#2695). Closed. */
 export const COMPOSITES_ENVIRONMENT_REASON_CODES = ENVIRONMENT_REASON_CODES;
 
+/** Why an environment row's executor names no forge workflow (#4402). Closed. */
+export const COMPOSITES_EXECUTOR_REASON_CODES = EXECUTOR_REASON_CODES;
+
 export interface CompositesMember {
   name: string;
   dir: string;

package/src/workspace/conformance/__writer_fixture__/work/work.schema.json

@@ -79,7 +79,7 @@
       "uniqueItems": true
     },
     "evidence": {
-      "description": "The proof of done: public links, or workspace files pinned by the hash of their bytes (chant workspace records pin <path>). May be empty while the work is open; a done item with none gets the warning work-done-unpinned. An entry that names a criterion from acceptance carries the verification it is and its result, and a manual verdict names who gave it in by (#2772).",
+      "description": "The proof of done: public links, workspace files pinned by the hash of their bytes (chant workspace records pin <path>), or ops results on the chant/lifecycle branch (#3171). May be empty while the work is open; a done item with none gets the warning work-done-unpinned. An entry that names a criterion from acceptance carries the verification it is and its result, and a manual verdict names who gave it in by (#2772).",
       "type": "array",
       "items": {
         "oneOf": [
@@ -88,6 +88,9 @@
           },
           {
             "$ref": "#/definitions/evidencePin"
+          },
+          {
+            "$ref": "#/definitions/evidenceOps"
           }
         ]
       }
@@ -305,6 +308,107 @@
         ]
       }
     },
+    "evidenceOps": {
+      "description": "An ops result on the chant/lifecycle branch (#3171): a run, a deploy, a gate answer or a release plan, named the way graph --intent's trace names a link. chant workspace work evidence and the workEvidence activity check it against the ledger before writing it, and a cited run's outcome agrees with result.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title",
+        "ops"
+      ],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ops": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ledger",
+            "ref",
+            "field",
+            "value",
+            "sha256"
+          ],
+          "properties": {
+            "ledger": {
+              "description": "Which ledger: an Op run, a deploy record, a gate answer or a release plan.",
+              "enum": [
+                "run",
+                "deploy",
+                "gate",
+                "plan"
+              ]
+            },
+            "ref": {
+              "description": "The ledger file, as chant/lifecycle:<path>.",
+              "type": "string",
+              "pattern": "^chant/lifecycle:"
+            },
+            "field": {
+              "description": "The field of the record that picks it out of the file, such as id, runId, timestamp or digest.",
+              "type": "string",
+              "minLength": 1
+            },
+            "value": {
+              "description": "That field's value.",
+              "type": "string",
+              "minLength": 1
+            },
+            "sha256": {
+              "description": "Hex SHA-256 of the record as the ledger stores it: the line, or the plan file.",
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            },
+            "env": {
+              "description": "The environment, for a run or a deploy.",
+              "type": "string"
+            },
+            "outcome": {
+              "description": "The run's status, for a run.",
+              "enum": [
+                "ok",
+                "fail"
+              ]
+            }
+          }
+        },
+        "as_of": {
+          "description": "When the result was cited, as an ISO 8601 timestamp.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "criterion": {
+          "description": "The acceptance criterion this evidence is for, by id (#2772).",
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+        },
+        "verification": {
+          "$ref": "#/definitions/verification"
+        },
+        "result": {
+          "description": "Whether the evidence shows the criterion met.",
+          "enum": [
+            "pass",
+            "fail"
+          ]
+        },
+        "by": {
+          "description": "Who produced the evidence: the lease holder for a steward's, the person for a manual verdict.",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "dependencies": {
+        "criterion": [
+          "verification",
+          "result"
+        ]
+      }
+    },
     "evidencePin": {
       "description": "A file in the workspace, pinned by the hash of its bytes. chant workspace records reports a file that changed or went missing since.",
       "type": "object",