@intentius/chant 0.108.0 → 0.109.0

package/src/fold-provenance.ts

@@ -70,7 +70,14 @@
  */
 
 import { isResourceDeclarable, type Declarable } from "./declarable";
-import { originOfPath, type EntityProvenance, type PathOrigin } from "./provenance";
+import { relative, isAbsolute } from "node:path";
+import {
+  originOfPath,
+  type ArgumentLocation,
+  type EntityProvenance,
+  type PathOrigin,
+  type SourceLocation,
+} from "./provenance";
 import type { DeepEntityDrift, PropertyDrift } from "./lifecycle/deep-diff";
 
 /** Why a field's origin could not be determined. Both are facts about the BUILD, not about the field. */
@@ -97,8 +104,17 @@ export type UnknownOriginReason =
  * address and "the `api` call of `AutoscaledService`" is.
  */
 export type FoldFieldOrigin =
-  | { kind: "composite-parameter"; composite: string; instance?: string; parameters: string[] }
-  | { kind: "composite-literal"; composite: string; instance?: string }
+  | {
+      kind: "composite-parameter";
+      composite: string;
+      instance?: string;
+      parameters: string[];
+      /** Where the composite call was written (chant #3597), when the build saw it. */
+      call?: SourceLocation;
+      /** Where each parameter's argument was written at that call, in `parameters` order. */
+      arguments?: ArgumentLocation[];
+    }
+  | { kind: "composite-literal"; composite: string; instance?: string; call?: SourceLocation }
   | { kind: "direct" }
   | { kind: "unknown"; reason: UnknownOriginReason };
 
@@ -110,6 +126,11 @@ export interface EntityFoldProvenance {
   composite?: string;
   /** The composite call (export name) it belongs to, when one expanded it. */
   instance?: string;
+  /**
+   * Where that composite call was written (chant #3597), when the fold
+   * interpreted the factory at a call it saw as written.
+   */
+  compositeCall?: SourceLocation;
   /**
    * Emitted property path to origin, in sorted key order. Every path the entity
    * emits is present: a path with no attribution carries an `unknown` origin
@@ -178,6 +199,7 @@ export function classifyFieldOrigin(
 ): FoldFieldOrigin {
   if (!provenance) return { kind: "unknown", reason: "no-provenance" };
   const instance = provenance.compositeInstance;
+  const call = provenance.compositeCall;
 
   switch (origin?.kind) {
     case "composite-parameter":
@@ -186,15 +208,29 @@ export function classifyFieldOrigin(
         composite: origin.composite,
         ...(instance ? { instance } : {}),
         parameters: [...origin.parameters],
+        ...(call ? { call: { ...call } } : {}),
+        ...(origin.arguments ? { arguments: origin.arguments.map((a) => ({ ...a })) } : {}),
       };
     case "composite-literal":
-      return { kind: "composite-literal", composite: origin.composite, ...(instance ? { instance } : {}) };
+      return {
+        kind: "composite-literal",
+        composite: origin.composite,
+        ...(instance ? { instance } : {}),
+        ...(call ? { call: { ...call } } : {}),
+      };
     case "composite":
       // The coarse kind: a composite expanded this, and nothing said which
       // parameter. Not a parameter, not a fixed literal, and above all not a
       // direct declaration.
       return { kind: "unknown", reason: "composite-not-interpreted" };
     case "authored":
+      // chant#3608 — `authored` is the file's own root record, and it reaches
+      // a path only when nothing finer did. On an entity a composite wrote (a
+      // member destructured from a composite the fold invoked) that means the
+      // fold could not attribute the path, which is `unknown`, never `direct`.
+      return provenance.composite
+        ? { kind: "unknown", reason: "composite-not-interpreted" }
+        : { kind: "direct" };
     case "build-param":
       // A build parameter governs the expression the AUTHOR wrote in their own
       // source, so the declaration is still theirs to edit.
@@ -224,6 +260,7 @@ export function foldProvenanceOfEntity(
     ...(provenance?.sourceFile ? { sourceFile: provenance.sourceFile } : {}),
     ...(provenance?.composite ? { composite: provenance.composite } : {}),
     ...(provenance?.compositeInstance ? { instance: provenance.compositeInstance } : {}),
+    ...(provenance?.compositeCall ? { compositeCall: { ...provenance.compositeCall } } : {}),
     fields,
   };
 }
@@ -278,9 +315,57 @@ function compositeCall(composite: string, instance: string | undefined): string
   return instance ? `the \`${instance}\` call of composite ${composite}` : `composite ${composite}`;
 }
 
-/** `in src/app.infra.ts`, or nothing when the build recorded no file. */
-function inFile(sourceFile: string | undefined): string {
-  return sourceFile ? ` in ${sourceFile}` : "";
+/** A file as a report prints it: relative to `root` when it is inside it, otherwise as recorded. */
+function displayFile(file: string, root: string | undefined): string {
+  if (!root || !isAbsolute(file)) return file;
+  const rel = relative(root, file);
+  return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : file;
+}
+
+/** `src/app.ts:12`, relative to `root` when it is inside it. */
+export function formatSourceLocation(location: SourceLocation, root?: string): string {
+  return `${displayFile(location.file, root)}:${location.line}`;
+}
+
+/** ` in src/app.infra.ts`, or nothing when the build recorded no file. */
+function inFile(sourceFile: string | undefined, root: string | undefined): string {
+  return sourceFile ? ` in ${displayFile(sourceFile, root)}` : "";
+}
+
+/**
+ * The composite call as the author wrote the arguments that govern a field:
+ * `WebApp({ replicas: 3 })`, or `WebApp({ iam: { path: "/service/" } })` for a
+ * nested parameter. Only arguments actually written at the call appear; when
+ * none is, the call is shown as `WebApp(...)`.
+ */
+export function describeCompositeArguments(composite: string, locations: readonly ArgumentLocation[]): string {
+  const written = locations.filter((a) => a.text !== undefined);
+  if (written.length === 0) return `${composite}(...)`;
+  const parts = written.map((a) => {
+    const outer = a.parameter.split(".").slice(0, -1);
+    return outer.reduceRight((inner, key) => `${key}: { ${inner} }`, a.text as string);
+  });
+  return `${composite}({ ${parts.join(", ")} })`;
+}
+
+/**
+ * Where a composite-parameter field was set, as `at src/app.ts:12`: the first
+ * argument written at the call, else the call, else the declaring file.
+ */
+function parameterSite(
+  origin: Extract<FoldFieldOrigin, { kind: "composite-parameter" }>,
+  sourceFile: string | undefined,
+  root: string | undefined,
+): string {
+  const written = origin.arguments?.find((a) => a.text !== undefined);
+  const location = written ?? origin.call ?? origin.arguments?.[0];
+  if (location) return ` at ${formatSourceLocation(location, root)}`;
+  return inFile(sourceFile, root);
+}
+
+/** ` at src/app.ts:10` for the composite call, else the declaring file. */
+function callSite(call: SourceLocation | undefined, sourceFile: string | undefined, root: string | undefined): string {
+  return call ? ` at ${formatSourceLocation(call, root)}` : inFile(sourceFile, root);
 }
 
 /** A value as a report prints it. */
@@ -327,6 +412,12 @@ export interface FieldReconcile {
   declared?: unknown;
   live?: unknown;
   origin: FoldFieldOrigin;
+  /**
+   * One line naming where the field came from (chant #3597):
+   * `spec.replicas on Deployment webDeployment comes from WebApp({ replicas: 3 }) at src/app.ts:12`.
+   * An `unknown` origin says so and why; it never reads as a direct declaration.
+   */
+  summary: string;
   resolution: DriftResolution;
 }
 
@@ -337,18 +428,48 @@ export interface FieldReconcile {
  * source declared, whose live value moved. Undeclared fields are held
  * elsewhere and never reach here, so the only question left is which of the
  * four origins produced the field.
+ *
+ * `entityType` names the resource in the summary line, and `root` (the
+ * project directory) makes the file names in it relative. Both are optional;
+ * without them the summary uses the entity name alone and absolute files.
  */
 export function resolveDriftedField(input: {
   entity: string;
+  entityType?: string;
   path: string;
   declared?: unknown;
   live?: unknown;
   origin?: PathOrigin;
   provenance?: EntityProvenance;
+  root?: string;
 }): FieldReconcile {
   const origin = classifyFieldOrigin(input.origin, input.provenance);
   const sourceFile = input.provenance?.sourceFile;
+  const root = input.root;
   const move = `${renderValue(input.declared)} to ${renderValue(input.live)}`;
+  const subject = `${input.path} on ${input.entityType ? `${input.entityType} ` : ""}${input.entity}`;
+
+  const summary = ((): string => {
+    switch (origin.kind) {
+      case "composite-parameter":
+        return (
+          `${subject} comes from ${describeCompositeArguments(origin.composite, origin.arguments ?? [])}` +
+          `${parameterSite(origin, sourceFile, root)}` +
+          (origin.arguments?.some((a) => a.text !== undefined)
+            ? ""
+            : ` (parameter ${origin.parameters.join(", ")}, not written at the call)`)
+        );
+      case "composite-literal":
+        return (
+          `${subject} is fixed inside composite ${origin.composite}; ` +
+          `no argument to the call${callSite(origin.call, sourceFile, root)} moves it`
+        );
+      case "direct":
+        return `${subject} is declared directly${inFile(sourceFile, root)}`;
+      case "unknown":
+        return `${subject} has an unknown origin: ${unknownOriginText(origin.reason)}`;
+    }
+  })();
 
   const resolution: DriftResolution = ((): DriftResolution => {
     switch (origin.kind) {
@@ -363,7 +484,7 @@ export function resolveDriftedField(input: {
           description:
             `change ${parameters.length === 1 ? "parameter" : "parameters"} ` +
             `${parameters.map((p) => `\`${p}\``).join(", ")} of ` +
-            `${compositeCall(origin.composite, origin.instance)}${inFile(sourceFile)} ` +
+            `${compositeCall(origin.composite, origin.instance)}${parameterSite(origin, sourceFile, root)} ` +
             `so \`${input.path}\` moves from ${move}. The composite stays.`,
         };
       }
@@ -375,14 +496,14 @@ export function resolveDriftedField(input: {
           ...(sourceFile ? { sourceFile } : {}),
           description:
             `refused: \`${input.path}\` is fixed by ${compositeCall(origin.composite, origin.instance)}` +
-            `${inFile(sourceFile)}, so no argument at the call site moves it. ` +
+            `${callSite(origin.call, sourceFile, root)}, so no argument at the call site moves it. ` +
             `Parameterize the field in composite ${origin.composite}, or stop using the composite here.`,
         };
       case "direct":
         return {
           kind: "edit-declaration",
           ...(sourceFile ? { sourceFile } : {}),
-          description: `change the declared value of \`${input.path}\`${inFile(sourceFile)} from ${move}.`,
+          description: `change the declared value of \`${input.path}\`${inFile(sourceFile, root)} from ${move}.`,
         };
       case "unknown":
         return {
@@ -391,7 +512,7 @@ export function resolveDriftedField(input: {
           ...(sourceFile ? { sourceFile } : {}),
           description:
             `origin unknown (${unknownOriginText(origin.reason)}), so falling back to changing the ` +
-            `declared value of \`${input.path}\`${inFile(sourceFile)} from ${move}.`,
+            `declared value of \`${input.path}\`${inFile(sourceFile, root)} from ${move}.`,
         };
     }
   })();
@@ -402,6 +523,7 @@ export function resolveDriftedField(input: {
     ...("declared" in input ? { declared: input.declared } : {}),
     ...("live" in input ? { live: input.live } : {}),
     origin,
+    summary,
     resolution,
   };
 }
@@ -420,6 +542,7 @@ export function resolveDriftedField(input: {
 export function resolveDeepDrift(
   drifted: readonly DeepEntityDrift[],
   provenanceOf: (entity: string) => EntityProvenance | undefined,
+  options: { root?: string } = {},
 ): FieldReconcile[] {
   const out: FieldReconcile[] = [];
   for (const entity of drifted) {
@@ -428,11 +551,13 @@ export function resolveDeepDrift(
       out.push(
         resolveDriftedField({
           entity: entity.name,
+          entityType: entity.type,
           path: change.path,
           ...("declared" in change ? { declared: change.declared } : {}),
           ...("live" in change ? { live: change.live } : {}),
           ...(change.origin ? { origin: change.origin } : {}),
           ...(provenance ? { provenance } : {}),
+          ...(options.root ? { root: options.root } : {}),
         }),
       );
     }

package/src/provenance.ts

@@ -32,6 +32,13 @@ export interface EntityProvenance {
    * collapse a composite to a single node at coarse diagram detail levels (#494).
    */
   compositeInstance?: string;
+  /**
+   * Where the composite call that expanded this entity was written (chant
+   * #3597): the `WebApp({...})` expression, not the factory body. Recorded
+   * only when the fold interpreted the factory at a call it could see; the
+   * run path and a nested call made from already-folded values leave it unset.
+   */
+  compositeCall?: SourceLocation;
   /**
    * Per-path origins within the entity's `props` (chant #1443). Read with
    * {@link originOfPath}, which does the prefix resolution these keys are
@@ -90,9 +97,46 @@ export type PathOrigin =
   | { kind: "authored" }
   | { kind: "composite"; composite: string; instance: string }
   | { kind: "build-param"; params: string[] }
-  | { kind: "composite-parameter"; composite: string; parameters: string[] }
+  | {
+      kind: "composite-parameter";
+      composite: string;
+      parameters: string[];
+      /**
+       * Where each parameter's argument was written at the composite call
+       * (chant #3597), in `parameters` order. Absent when the build did not
+       * see the call; see {@link ArgumentLocation} for the fallback.
+       */
+      arguments?: ArgumentLocation[];
+    }
   | { kind: "composite-literal"; composite: string };
 
+/**
+ * A place in a source file. `file` is absolute, as
+ * {@link EntityProvenance.sourceFile} is; `line` and `column` are 1-based, the
+ * way an editor and `file:line:column` print them.
+ */
+export interface SourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+
+/**
+ * Where one composite parameter's argument was written at the call (chant
+ * #3597). When the call's argument object has a property at the parameter's
+ * path, the location is that property and `text` is the property as written
+ * (`replicas: 3`). When it does not (the parameter was left out, or arrived
+ * through a spread or a non-literal argument), the location is the call's own
+ * and `text` is absent: the call is the nearest place that governs it, and
+ * nothing claims a property that is not there.
+ */
+export interface ArgumentLocation extends SourceLocation {
+  /** The factory parameter path, as in `parameters` (`replicas`, `iam.path`). */
+  parameter: string;
+  /** The innermost property as written at the call, when one is. */
+  text?: string;
+}
+
 /** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
 function isPathPrefix(prefix: string, path: string): boolean {
   if (prefix === "") return true;
@@ -114,6 +158,7 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
     existing.sourceFile ??= prov.sourceFile;
     existing.composite ??= prov.composite;
     existing.compositeInstance ??= prov.compositeInstance;
+    existing.compositeCall ??= prov.compositeCall;
     if (prov.paths) {
       existing.paths ??= {};
       for (const [path, origin] of Object.entries(prov.paths)) {

package/src/workspace/ci-green-cli.ts

@@ -4,6 +4,7 @@
  *   ci last-green [--json]               the newest commit on the branch with a green tag and no revoked tag
  *   ci tick [--dry-run] [--forge github] tag the commits that turned green, revoke the ones that turned red
  *   ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>]
+ *               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
  *                                        write the root CI file that runs the tick
  *
  * `last-green --json` prints `ci-last-green.schema.json`. The tick and the
@@ -17,12 +18,12 @@ import type { CommandContext } from "../cli/registry";
 import { findWorkspaceRoot } from "../project-root";
 import { ciTick, CiGreenError, formatTick, lastGreen } from "./ci-green";
 import { ciForgeFromEnv } from "./ci-green-forge";
-import { CI_GREEN_WORKFLOW_FILE, ciGreenHeader, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
+import { ACTIONS_NAME, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, type PushToken, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
 import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
 import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline";
 import { gitTop, workingTree } from "./tree";
 
-const USAGE = "chant ci last-green [--json] | ci tick [--dry-run] [--forge github] | ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>]";
+const USAGE = "chant ci last-green [--json] | ci tick [--dry-run] [--forge github] | ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>] [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]";
 
 export async function runCiLastGreen(ctx: CommandContext): Promise<number> {
   const doc = lastGreen({ cwd: process.cwd() });
@@ -56,9 +57,23 @@ export async function runCiTick(ctx: CommandContext): Promise<number> {
   }
 }
 
+/** The push token the flags ask for, or none for the Actions token. Throws on a half-given or clashing pair. */
+function pushToken(args: CommandContext["args"]): PushToken | undefined {
+  const { ciTokenSecret: secret, ciAppIdVar: appIdVar, ciAppKeySecret: appKeySecret } = args;
+  for (const [flag, name] of [["--token-secret", secret], ["--app-id-var", appIdVar], ["--app-key-secret", appKeySecret]] as const) {
+    if (name !== undefined && !ACTIONS_NAME.test(name)) throw new Error(`${flag} takes a secret or variable name, letters, digits and underscores, not ${JSON.stringify(name)}`);
+  }
+  if (secret !== undefined && (appIdVar !== undefined || appKeySecret !== undefined)) throw new Error("--token-secret and --app-id-var/--app-key-secret each name the push token; pass one or the other");
+  if ((appIdVar === undefined) !== (appKeySecret === undefined)) throw new Error("a GitHub App token needs both the App's id and its key: --app-id-var <VAR> --app-key-secret <NAME>");
+  if (secret !== undefined) return { secret };
+  if (appIdVar !== undefined && appKeySecret !== undefined) return { appIdVar, appKeySecret };
+  return undefined;
+}
+
 export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
   const cwd = process.cwd();
   try {
+    const push = pushToken(ctx.args);
     const found = findWorkspaceRoot(cwd);
     if (!found) throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root");
     const declaration = readDeclaration(workingTree(found.dir));
@@ -85,11 +100,13 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     if (ctx.args.output) parts.push("--output", relative(base, target).split(sep).join("/"));
     if (ctx.args.ciChant) parts.push("--chant", ctx.args.ciChant);
     if (ctx.args.ciInstall) parts.push("--install", ctx.args.ciInstall);
+    if (push && "secret" in push) parts.push("--token-secret", push.secret);
+    if (push && "appIdVar" in push) parts.push("--app-id-var", push.appIdVar, "--app-key-secret", push.appKeySecret);
     const command = parts.map(shellArg).join(" ");
     const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
     // The install runs in the workspace root, so its lockfile there keys setup-node's npm cache.
     const npmLock = ctx.args.ciInstall && existsSync(join(root, "package-lock.json")) ? (workspaceRoot === "." ? "package-lock.json" : `${workspaceRoot}/package-lock.json`) : undefined;
-    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock });
+    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push });
     const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
     if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
     console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}, and every 15 minutes.`);

package/src/workspace/ci-green-workflow.test.ts

@@ -115,6 +115,38 @@ describe("the workflows that hold required check runs (#3573)", () => {
   });
 });
 
+describe("the token the tick pushes its tags with (#3573)", () => {
+  const base = { green, workflows: ["ci"], chantVersion: "0.108.0", workspaceRoot: "." };
+
+  test("without one, checkout persists the Actions token and the tick reads check runs with it", () => {
+    const steps = (parseYAMLDocument(renderCiGreenWorkflow(base)) as Yaml).jobs.tick.steps;
+    expect(steps[0].with.token).toBeUndefined();
+    expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+  });
+
+  test("--token-secret checks out with the secret, so the push uses it, and nothing else changes", () => {
+    const plain = renderCiGreenWorkflow(base);
+    const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
+    const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
+    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN }}" } });
+    // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
+    expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+    expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
+    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN }}\n", "")).toBe(plain);
+  });
+
+  test("--app-id-var and --app-key-secret mint an App token before the checkout and check out with it", () => {
+    const steps = (parseYAMLDocument(renderCiGreenWorkflow({ ...base, push: { appIdVar: "CI_GREEN_APP_ID", appKeySecret: "CI_GREEN_APP_KEY" } })) as Yaml).jobs.tick.steps;
+    expect(steps[0]).toMatchObject({
+      id: "app-token",
+      uses: "actions/create-github-app-token@v2",
+      with: { "app-id": "${{ vars.CI_GREEN_APP_ID }}", "private-key": "${{ secrets.CI_GREEN_APP_KEY }}" },
+    });
+    expect(steps[1].with.token).toBe("${{ steps.app-token.outputs.token }}");
+    expect(steps[3].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+  });
+});
+
 describe("chant ci workflow (#3573)", () => {
   test("writes the file with its header, records it on the member it ran in, and writes the same bytes twice", async () => {
     const root = scratchDir("chant-ci-workflow-");
@@ -179,6 +211,64 @@ describe("chant ci workflow (#3573)", () => {
     }
   });
 
+  test("--token-secret goes into the file and its header, and without it the bytes are what they were", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, { "chant.workspace.json": declaration([], { ci: { green: GREEN } }), ".github/workflows/ci.yml": CI, ".github/workflows/macos.yml": MACOS });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const file = join(root, CI_GREEN_WORKFLOW_FILE);
+      expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(0);
+      const plain = readFileSync(file, "utf-8");
+      expect(plain).not.toMatch(/token:|secrets\./);
+
+      expect(await runCiWorkflow({ args: { ciTokenSecret: "CI_GREEN_TOKEN" } } as unknown as CommandContext)).toBe(0);
+      const withToken = readFileSync(file, "utf-8");
+      expect(withToken.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --token-secret CI_GREEN_TOKEN (in the workspace root)`);
+      const steps = (parseYAMLDocument(withToken) as Yaml).jobs.tick.steps;
+      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN }}");
+      expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
+
+      const app = { args: { ciAppIdVar: "CI_GREEN_APP_ID", ciAppKeySecret: "CI_GREEN_APP_KEY" } } as unknown as CommandContext;
+      expect(await runCiWorkflow(app)).toBe(0);
+      expect(readFileSync(file, "utf-8").split("\n")[0]).toBe(
+        `# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --app-id-var CI_GREEN_APP_ID --app-key-secret CI_GREEN_APP_KEY (in the workspace root)`,
+      );
+
+      // Dropping the flag writes the bytes chant 0.108.0 wrote.
+      expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(0);
+      expect(readFileSync(file, "utf-8")).toBe(plain);
+    } finally {
+      cwd.mockRestore();
+      log.mockRestore();
+      error.mockRestore();
+    }
+  });
+
+  test("refuses a half-given App, both kinds of token at once, and a name GitHub wouldn't accept", async () => {
+    const root = scratchDir("chant-ci-workflow-");
+    git(root, "init", "-q");
+    writeFiles(root, { "chant.workspace.json": declaration([], { ci: { green: GREEN } }), ".github/workflows/ci.yml": CI });
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    const errors: string[] = [];
+    const error = vi.spyOn(console, "error").mockImplementation((s: unknown) => void errors.push(String(s)));
+    try {
+      const run = (args: Record<string, string>) => runCiWorkflow({ args } as unknown as CommandContext);
+      expect(await run({ ciAppIdVar: "APP_ID" })).toBe(1);
+      expect(errors.pop()).toMatch(/both the App's id and its key/);
+      expect(await run({ ciTokenSecret: "T", ciAppIdVar: "APP_ID", ciAppKeySecret: "APP_KEY" })).toBe(1);
+      expect(errors.pop()).toMatch(/one or the other/);
+      expect(await run({ ciTokenSecret: "ci-green token" })).toBe(1);
+      expect(errors.pop()).toMatch(/--token-secret takes a secret or variable name/);
+      expect(existsSync(join(root, CI_GREEN_WORKFLOW_FILE))).toBe(false);
+    } finally {
+      cwd.mockRestore();
+      error.mockRestore();
+    }
+  });
+
   test("refuses to write a workflow nothing but the schedule would trigger", async () => {
     const root = scratchDir("chant-ci-workflow-");
     git(root, "init", "-q");

package/src/workspace/ci-green-workflow.ts

@@ -22,6 +22,16 @@
  * the workspace root has a `package-lock.json`. chant's own repository uses
  * both to run its source at the commit it checks out.
  *
+ * The tick pushes its tags with the credentials actions/checkout leaves in
+ * the clone, the Actions token by default. GitHub treats a new ref to a
+ * commit whose workflow files differ from the default branch's as an update
+ * to those workflows, and the Actions token can never hold the `workflows`
+ * permission, so it is refused there. `--token-secret <NAME>` checks out
+ * with `secrets.<NAME>` instead, and `--app-id-var <VAR> --app-key-secret
+ * <NAME>` mints a GitHub App token first and checks out with that. The
+ * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
+ * a fine-grained personal access token can't call the Checks API.
+ *
  * Like a member's pipelines (./member-pipeline.ts), the file starts with the
  * generated-file header naming the command, and the member whose directory
  * the command runs in records it in its generated-file record, so `WSP081`
@@ -143,14 +153,39 @@ export interface WorkflowInput {
   npmLock?: string;
   /** The workspace root relative to the repository root, `.` for the root itself. */
   workspaceRoot: string;
+  /** How the tag push authenticates, when not with the Actions token. */
+  push?: PushToken;
 }
 
+/**
+ * A token the checkout persists for the tick's `git push`: a repository
+ * secret, or a GitHub App's installation token minted from its id (an
+ * Actions variable) and private key (a secret).
+ */
+export type PushToken = { secret: string } | { appIdVar: string; appKeySecret: string };
+
+/** A secret or variable name GitHub accepts: letters, digits and underscores, not starting with a digit. */
+export const ACTIONS_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
 /** The workflow's YAML, without the generated-file header. Deterministic: the same input writes the same bytes. */
 export function renderCiGreenWorkflow(input: WorkflowInput): string {
   const { green } = input;
   const where = input.workspaceRoot === "." ? [] : [`        working-directory: ${q(input.workspaceRoot)}`];
   const cache = input.install && input.npmLock ? ["          cache: npm", ...(input.npmLock === "package-lock.json" ? [] : [`          cache-dependency-path: ${q(input.npmLock)}`])] : [];
   const tick = input.chant ? q(`${input.chant} ci tick`) : `npx --yes @intentius/chant@${input.chantVersion} ci tick`;
+  const push = input.push;
+  const mint =
+    push && "appIdVar" in push
+      ? [
+          "      - name: Mint a GitHub App token that may push tags to commits that change workflows",
+          "        id: app-token",
+          "        uses: actions/create-github-app-token@v2",
+          "        with:",
+          `          app-id: \${{ vars.${push.appIdVar} }}`,
+          `          private-key: \${{ secrets.${push.appKeySecret} }}`,
+        ]
+      : [];
+  const token = !push ? [] : ["secret" in push ? `          token: \${{ secrets.${push.secret} }}` : "          token: ${{ steps.app-token.outputs.token }}"];
   const lines = [
     `name: ${CI_GREEN_WORKFLOW_NAME}`,
     "",
@@ -182,10 +217,12 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     "    runs-on: ubuntu-latest",
     "    timeout-minutes: 15",
     "    steps:",
+    ...mint,
     "      - uses: actions/checkout@v6",
     "        with:",
     `          ref: ${q(green.branch)}`,
     "          fetch-depth: 0",
+    ...token,
     "      - uses: actions/setup-node@v6",
     "        with:",
     "          node-version: \"24\"",

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

@@ -5,10 +5,12 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { chmodSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { afterAll, describe, expect, test, vi } from "vitest";
 import { parseDeclaration, type CiPhase } from "./declaration";
 import { cleanScratch, contract, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
-import { ciTick, evaluateCommit, evaluatePhase, latestAttempts, lastGreen, matchesCheckRun, windowMs, type LastGreenDocument } from "./ci-green";
+import { ciTick, pushRefusalCause, evaluateCommit, evaluatePhase, latestAttempts, lastGreen, matchesCheckRun, windowMs, type LastGreenDocument } from "./ci-green";
 import type { CheckRun, CiForge } from "./ci-green-forge";
 import { runCiLastGreen } from "./ci-green-cli";
 import lastGreenSchema from "./ci-last-green.schema.json";
@@ -281,6 +283,30 @@ describe("chant ci tick (#3573)", () => {
     expect(remoteTags(origin)).toEqual([]);
     expect(git(root, "tag", "-l")).toBe("");
   });
+
+  test("a push GitHub refuses for lack of the workflows permission names the cause and the flags that fix it", async () => {
+    const { root, origin } = workspace();
+    const a = commitAt(root, 1, "app/a.txt");
+    push(root);
+    // The bare origin refuses tags the way GitHub does when the tagged commit changes a workflow file.
+    const hook = join(origin, "hooks", "pre-receive");
+    writeFileSync(
+      hook,
+      "#!/bin/sh\necho 'refusing to allow a GitHub App to create or update workflow `.github/workflows/check.yml` without `workflows` permission' >&2\nexit 1\n",
+    );
+    chmodSync(hook, 0o755);
+    const tick = ciTick({ cwd: root, forge: fakeForge(new Map([[a, PASSING]])), now: NOW });
+    await expect(tick).rejects.toThrow(/could not push ci\/green\/[0-9a-f]+ to origin: GitHub refused the tag push because the tagged commit changes workflow files, and GITHUB_TOKEN can't update workflows: regenerate the workflow with --token-secret <NAME>/);
+    await expect(ciTick({ cwd: root, forge: fakeForge(new Map([[a, PASSING]])), now: NOW })).rejects.toThrow(/without `workflows` permission/);
+    expect(remoteTags(origin)).toEqual([]);
+  });
+
+  test("other push refusals get no workflows hint", () => {
+    expect(pushRefusalCause("! [remote rejected] ci/green/abc -> ci/green/abc (refusing to allow a GitHub App to create or update workflow .github/workflows/check.yml without workflows permission)")).toMatch(/--token-secret/);
+    expect(pushRefusalCause("refusing to allow an OAuth App to create or update workflow `.github/workflows/x.yml` without `workflow` scope")).toMatch(/--app-id-var/);
+    expect(pushRefusalCause("! [rejected] ci/green/abc -> ci/green/abc (already exists)")).toBeNull();
+    expect(pushRefusalCause("remote: Permission to o/r.git denied to github-actions[bot].")).toBeNull();
+  });
 });
 
 // ── last-green ───────────────────────────────────────────────────────────────

package/src/workspace/ci-green.ts

@@ -326,12 +326,28 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
       git(top, ["push", "--quiet", remote, ...due.map((c) => `refs/tags/${c.made!.tag}`)]);
     } catch (err) {
       // The local tags stay until the next tick's fetch prunes the ones the remote lacks.
-      throw new Error(`could not push ${due.map((c) => c.made!.tag).join(", ")} to ${remote}: ${stderrOf(err)}`);
+      const stderr = stderrOf(err);
+      const cause = pushRefusalCause(stderr);
+      throw new Error(`could not push ${due.map((c) => c.made!.tag).join(", ")} to ${remote}: ${cause ? `${cause}\n` : ""}${stderr}`);
     }
   }
   return { branch: green.branch, window: green.window, ref: tracking, commits: planned, made: due.map((c) => c.made!.tag) };
 }
 
+/**
+ * Why the remote refused a tag push, when chant can tell. GitHub refuses a
+ * new ref to a commit whose workflow files differ from the default branch's
+ * unless the token may update workflows, and the Actions token never may.
+ */
+export function pushRefusalCause(stderr: string): string | null {
+  if (!/without [`']?workflows?[`']? (permission|scope)/i.test(stderr)) return null;
+  return (
+    "GitHub refused the tag push because the tagged commit changes workflow files, and GITHUB_TOKEN can't update workflows: " +
+    "regenerate the workflow with --token-secret <NAME>, naming a secret that holds a fine-grained token with Contents and Workflows read and write, " +
+    "or with --app-id-var <VAR> --app-key-secret <NAME> for a GitHub App's token"
+  );
+}
+
 /** A tagger for an annotated tag when git has none configured, as on a fresh CI runner. The environment's GIT_COMMITTER_* still win. */
 function taggerConfig(top: string): string[] {
   const out: string[] = [];