@intentius/chant-lexicon-github 0.101.0 → 0.104.0

package/src/components/__fixtures__/pr-loop.github.golden.yml

@@ -0,0 +1,68 @@
+name: chant-pr-prod
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+env:
+  CHANT_ENV: prod
+
+jobs:
+  plan:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    container: node:22-slim
+    permissions:
+      contents: read
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Plan the members this pull request reaches
+        env:
+          BASE_SHA: '${{ github.event.pull_request.base.sha }}'
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+        run: chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github
+      - name: Keep the plan report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chant-pr-plan
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true
+  apply:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    container: node:22-slim
+    concurrency:
+      group: chant-apply-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Apply the plan a reviewer approved
+        env:
+          BASE_SHA: '${{ github.event.before }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+        run: chant components pr-apply --base "$BASE_SHA" --env prod --gate pr-apply --output .chant/pr --forge github --require-review
+      - name: Keep the apply report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chant-pr-apply
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true

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

@@ -72,7 +72,7 @@ describe("generateGithubOpPipeline: one file per scheduled Op", () => {
     const job = doc.jobs!["actions-audit"];
 
     expect(job["runs-on"]).toBe("ubuntu-latest");
-    expect(job.steps[0].uses).toBe("actions/checkout@v4");
+    expect(job.steps[0].uses).toBe("actions/checkout@v7");
     const runStep = job.steps.find((s) => typeof s.run === "string")!;
     expect(runStep.run).toBe("chant run actions-audit");
   });
@@ -327,7 +327,7 @@ describe("generateGithubOpPipeline: setup steps and additive permissions (#2242)
     const steps = doc.jobs!["app-apply"].steps;
 
     expect(steps.slice(0, 3).map((s) => s.uses ?? s.run)).toEqual([
-      "actions/checkout@v4",
+      "actions/checkout@v7",
       "aws-actions/configure-aws-credentials@v6",
       "install terraform",
     ]);
@@ -385,7 +385,7 @@ describe("generateGithubOpPipeline: setup steps and additive permissions (#2242)
     ];
     const steps = parseFile(generateGithubOpPipeline(specs).files[0].yaml).jobs!["app-apply"].steps;
     expect(steps.map((s) => s.uses).filter(Boolean)).toEqual([
-      "actions/checkout@v4",
+      "actions/checkout@v7",
       "github/codeql-action/upload-sarif@v4",
       "aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83",
     ]);
@@ -622,7 +622,7 @@ describe("generateGithubOpPipeline: a deployment environment on the Op's job (#2
       "    runs-on: ubuntu-latest",
       "    container: node:22-slim",
       "    steps:",
-      "      - uses: actions/checkout@v4",
+      "      - uses: actions/checkout@v7",
       "      - run: chant run actions-audit",
       "        env:",
       "          GITHUB_TOKEN: '${{ github.token }}'",

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

@@ -70,7 +70,7 @@
  * that job either, same as `environment:` above does not).
  */
 
-import { emitYAML } from "@intentius/chant/yaml";
+import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
 import { memberPathFilter, resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGithubOpOptions,
@@ -83,6 +83,7 @@ import type {
   PipelineMember,
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
+import { actionRef } from "../action-pins";
 
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 
@@ -709,7 +710,7 @@ export function buildGithubOpPipelineDocs(
       ? [...runParts, ...GATED_EXIT_FLAG, "--json"].join(" ")
       : runParts.join(" ");
 
-    const steps: Array<Record<string, unknown>> = [{ uses: "actions/checkout@v4" }];
+    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
     for (const step of setup) steps.push(setupStepDoc(step));
     for (const line of beforeScript) steps.push({ run: line });
     steps.push(
@@ -822,14 +823,14 @@ export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
   // it was before the field existed.
   if (doc.header && doc.header.length > 0) sections.push(doc.header.join("\n"));
   if (doc.name) sections.push("name: " + emitYAML(doc.name, 0));
-  sections.push("on:" + emitYAML(doc.on, 1));
-  if (doc.env && Object.keys(doc.env).length > 0) sections.push("env:" + emitYAML(doc.env, 1));
-  sections.push("concurrency:" + emitYAML(doc.concurrency, 1));
-  if (Object.keys(doc.permissions).length > 0) sections.push("permissions:" + emitYAML(doc.permissions, 1));
+  sections.push(emitYAMLEntry("on", doc.on));
+  if (doc.env && Object.keys(doc.env).length > 0) sections.push(emitYAMLEntry("env", doc.env));
+  sections.push(emitYAMLEntry("concurrency", doc.concurrency));
+  if (Object.keys(doc.permissions).length > 0) sections.push(emitYAMLEntry("permissions", doc.permissions));
   // The gated-apply notice job rides in `jobs:` beside the Op's own job, but
   // is carried separately on the doc so a dialect that cannot run it (forgejo,
   // whose runner has no `gh` pointed at its own instance) drops it by omission.
-  sections.push("jobs:" + emitYAML({ ...doc.jobsDoc, ...(doc.gatedNoticeDoc ?? {}) }, 1));
+  sections.push(emitYAMLEntry("jobs", { ...doc.jobsDoc, ...(doc.gatedNoticeDoc ?? {}) }));
   return sections.join("\n\n") + "\n";
 }
 

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

@@ -104,7 +104,7 @@ describe("generateGithubPipeline: structurally valid YAML", () => {
       expect(job.steps.length).toBeGreaterThan(0);
       // Every job starts with a checkout step — a job runs on a fresh runner
       // with no repo present, unlike GitLab's auto-cloned workspace.
-      expect(job.steps[0].uses).toBe("actions/checkout@v4");
+      expect(job.steps[0].uses).toBe("actions/checkout@v7");
     }
   });
 
@@ -421,3 +421,32 @@ describe("generateGithubPipeline: a promote job (#2575)", () => {
     expect(artifactRoot(["/tmp/out/a.tar", "/tmp/out/b.tar"])).toBe("/tmp/out");
   });
 });
+
+describe("generateGithubPipeline: gated waves (#3049)", () => {
+  const roots: DriverComponent[] = [
+    { name: "net", deploy: [] },
+    { name: "a", dependsOn: ["net"], deploy: [] },
+    { name: "app", dependsOn: ["a"], deploy: [] },
+  ];
+
+  test("one job per wave, each handing the attempt record to the next", () => {
+    const result = generateGithubPipeline(roots, { env: "prod", gatedWaves: { gate: "release" } });
+    const parsed = parseYAML(result.yaml) as { jobs: Record<string, { needs?: string[]; steps: Array<Record<string, unknown>> }> };
+    expect(Object.keys(parsed.jobs)).toEqual(["wave-1", "wave-2", "wave-3"]);
+    expect(parsed.jobs["wave-2"].needs).toEqual(["wave-1"]);
+
+    const steps = parsed.jobs["wave-2"].steps;
+    expect(steps[0].with).toEqual({ "fetch-depth": 0 });
+    expect(steps[1]).toMatchObject({ uses: "actions/download-artifact@v4", with: { name: "fan-out-record-wave-1", path: ".chant" } });
+    expect(steps[2].run).toBe(
+      "chant components fan-out --base HEAD~1 --env prod --wave-gate release --wave 2 --resume .chant/fan-out.json",
+    );
+    expect(steps[3]).toMatchObject({ if: "always()", with: { name: "fan-out-record-wave-2", path: ".chant/fan-out.json" } });
+    // Wave 1 has nothing to download.
+    expect(parsed.jobs["wave-1"].steps.some((s) => s.uses === "actions/download-artifact@v4")).toBe(false);
+  });
+
+  test("a gated-wave pipeline has no promote job", () => {
+    expect(() => generateGithubPipeline(roots, { gatedWaves: { gate: "release" }, promoteTo: "prod" })).toThrow(/no promote job/);
+  });
+});

package/src/components/generate-pipeline.ts

@@ -56,9 +56,11 @@
  * touching the component declarations.
  */
 
-import { emitYAML } from "@intentius/chant/yaml";
+import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
+import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
+import { PR_LOOP_REPORT_DIR, prApplyGroup, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -66,6 +68,7 @@ import type {
   ComponentPipelineResult as GenerateGithubResult,
   PipelineMember,
 } from "@intentius/chant/lexicon";
+import { actionRef } from "../action-pins";
 
 export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
 
@@ -106,6 +109,140 @@ export interface GithubPipelineDoc {
   jobs: GeneratedJob[];
 }
 
+/** The workflow artifact the gated-wave jobs hand their attempt record through, one per wave. */
+function waveRecordArtifact(wave: number): string {
+  return `fan-out-record-wave-${wave}`;
+}
+
+/**
+ * The gated-wave workflow (#3049): one job per wave, each running one wave of
+ * `chant components fan-out --wave-gate`, chained by `needs:`. Each job
+ * downloads the record the job before it uploaded and uploads its own, even
+ * when it stops at a gate (exit 3), so re-running it after `chant approve`
+ * reads the record. The checkout fetches full history for `--base`.
+ */
+function gatedWaveGithubDoc(
+  components: DriverComponent[],
+  env: string,
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  options: GenerateGithubOptions,
+): GithubPipelineDoc {
+  const waveJobs = gatedWaveJobs(components, env, options.gatedWaves!);
+  const jobsDoc: Record<string, unknown> = {};
+  const jobs: GeneratedJob[] = [];
+  for (const job of waveJobs) {
+    jobs.push({ jobName: job.jobName, component: `wave ${job.wave}`, stage: job.jobName, needs: job.needs });
+    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } }];
+    if (job.wave > 1) {
+      steps.push({
+        name: `Download the record wave ${job.wave - 1} left`,
+        uses: "actions/download-artifact@v4",
+        with: { name: waveRecordArtifact(job.wave - 1), path: dirnameOf(GATED_WAVE_RECORD) },
+      });
+    }
+    for (const line of beforeScript) steps.push({ run: line });
+    steps.push({ run: job.command.join(" ") });
+    for (const line of extraScript) steps.push({ run: line });
+    steps.push({
+      name: `Upload the record for wave ${job.wave}`,
+      if: "always()",
+      uses: "actions/upload-artifact@v4",
+      with: {
+        name: waveRecordArtifact(job.wave),
+        path: GATED_WAVE_RECORD,
+        "if-no-files-found": "ignore",
+        "include-hidden-files": true,
+        overwrite: true,
+      },
+    });
+    jobsDoc[job.jobName] = {
+      "runs-on": "ubuntu-latest",
+      ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+      container: image,
+      steps,
+    };
+  }
+  const doc: GithubPipelineDoc = {
+    name: `chant-components-${env}`,
+    environment: env,
+    on: { workflow_dispatch: {} },
+    env: { ...options.variables, CHANT_ENV: env },
+    jobsDoc,
+    stages: waveJobs.map((j) => j.jobName),
+    jobs,
+  };
+  return options.member ? scopeToMember(doc, options.member) : doc;
+}
+
+/**
+ * The pull-request workflow (#3183): `plan` on each pull request into the
+ * target branch, `apply` on each push to it. The plan job can comment and set
+ * statuses but cannot push, since it runs the pull request's code; the apply
+ * job can push, to record a pending fact on `chant/lifecycle`, and runs one
+ * at a time per environment. Both keep their report as an artifact, and both
+ * check out the full history, since each measures the change with git.
+ */
+function prLoopGithubDoc(
+  env: string,
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  options: GenerateGithubOptions,
+): GithubPipelineDoc {
+  const loop = options.prLoop!;
+  const branch = loop.branch ?? "main";
+  const [plan, apply] = prLoopJobs(loop.forge ?? "github", env, loop);
+  const steps = (job: typeof plan, name: string): Array<Record<string, unknown>> => [
+    { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } },
+    ...beforeScript.map((line) => ({ run: line })),
+    { name, env: job.env, run: job.command },
+    ...extraScript.map((line) => ({ run: line })),
+    {
+      name: `Keep the ${job.jobName} report`,
+      if: "always()",
+      uses: "actions/upload-artifact@v4",
+      with: { name: `chant-pr-${job.jobName}`, path: PR_LOOP_REPORT_DIR, "if-no-files-found": "ignore", "include-hidden-files": true },
+    },
+  ];
+  const jobsDoc: Record<string, unknown> = {
+    plan: {
+      if: "github.event_name == 'pull_request'",
+      "runs-on": "ubuntu-latest",
+      container: image,
+      permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
+      steps: steps(plan, "Plan the members this pull request reaches"),
+    },
+    apply: {
+      if: "github.event_name == 'push'",
+      "runs-on": "ubuntu-latest",
+      container: image,
+      concurrency: { group: prApplyGroup(env), "cancel-in-progress": false },
+      permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
+      steps: steps(apply, "Apply the plan a reviewer approved"),
+    },
+  };
+  return {
+    name: `chant-pr-${env}`,
+    environment: env,
+    on: { pull_request: { branches: [branch] }, push: { branches: [branch] } },
+    env: { ...options.variables, CHANT_ENV: env },
+    jobsDoc,
+    stages: ["plan", "apply"],
+    jobs: [
+      { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
+      { jobName: "apply", component: "pull request apply", stage: "apply", needs: [] },
+    ],
+  };
+}
+
+/** The directory part of a relative path, `.` when there is none. */
+function dirnameOf(path: string): string {
+  const i = path.lastIndexOf("/");
+  return i <= 0 ? "." : path.slice(0, i);
+}
+
 /** GitHub Actions job ids must match `[a-zA-Z_][a-zA-Z0-9_-]*`; component names are already kebab-case in every fixture, but normalize defensively (mirrors gitlab's `toJobName`). */
 function toJobName(componentName: string): string {
   return componentName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
@@ -173,6 +310,19 @@ export function buildGithubPipelineDoc(
   const { waves } = resolveComponentGraph(components);
   const byName = new Map(components.map((c) => [c.name, c]));
 
+  if (options.prLoop) {
+    if (options.gatedWaves || options.promoteTo !== undefined) {
+      throw new Error("a pull-request pipeline has no wave or promote jobs; drop --wave-gate and --promote-to, or --pr-loop");
+    }
+    if (options.member) throw new Error("a pull-request pipeline is not generated for a workspace member yet; generate it from the project outside the workspace");
+    return prLoopGithubDoc(env, image, beforeScript, extraScript, options);
+  }
+
+  if (options.gatedWaves) {
+    if (options.promoteTo !== undefined) throw new Error("a gated-wave pipeline has no promote job; drop --promote-to or --wave-gate");
+    return gatedWaveGithubDoc(components, env, image, beforeScript, extraScript, options);
+  }
+
   // Components that something else depends on must hand their resolved outputs
   // (stack outputs, published artifact refs) to their dependents, which run as
   // separate jobs on separate runners. Each such producer dumps its outputs to
@@ -232,7 +382,7 @@ export function buildGithubPipelineDoc(
       // One step per script line — mirrors gitlab's `script:` array of
       // discrete shell lines, rather than a single multi-line `run:` block, so
       // each line is independently inspectable (and machine-parseable).
-      const steps: Array<Record<string, unknown>> = [{ uses: "actions/checkout@v4" }];
+      const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
 
       for (const dep of component.dependsOn ?? []) {
         steps.push({
@@ -297,7 +447,7 @@ export function buildGithubPipelineDoc(
     for (const name of [...pinned].sort()) {
       command.push("--digest", `"${name}=\${{ needs.${jobNameByComponent.get(name)!}.outputs.digest }}"`);
     }
-    const steps: Array<Record<string, unknown>> = [{ uses: "actions/checkout@v4" }];
+    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
     for (const [name, paths] of archives) {
       steps.push({
         name: `Download ${name} build archive`,
@@ -375,21 +525,14 @@ function memberArtifactStep(step: Record<string, unknown>, member: PipelineMembe
  * Shared with the forgejo dialect (#969), which transforms the doc first.
  */
 export function emitPipelineYAML(doc: GithubPipelineDoc): string {
-  // A block value starts with a newline; an inline one (`{}` for an empty
-  // component set) needs the space after the colon, or `jobs:{}` is a plain
-  // scalar rather than a key (#2991).
-  const section = (key: string, value: unknown): string => {
-    const emitted = emitYAML(value, 1);
-    return `${key}:${emitted.startsWith("\n") ? "" : " "}${emitted}`;
-  };
   const sections: string[] = [];
   sections.push("name: " + emitYAML(doc.name, 0));
-  sections.push(section("on", doc.on));
+  sections.push(emitYAMLEntry("on", doc.on));
   if (doc.env && Object.keys(doc.env).length > 0) {
-    sections.push(section("env", doc.env));
+    sections.push(emitYAMLEntry("env", doc.env));
   }
-  if (doc.defaults) sections.push(section("defaults", doc.defaults));
-  sections.push(section("jobs", doc.jobsDoc));
+  if (doc.defaults) sections.push(emitYAMLEntry("defaults", doc.defaults));
+  sections.push(emitYAMLEntry("jobs", doc.jobsDoc));
   return sections.join("\n\n") + "\n";
 }
 

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

@@ -0,0 +1,98 @@
+/**
+ * The generated pull-request workflow for GitHub Actions (#3183): a plan job
+ * on each pull request, an apply job on each push to the target branch. The
+ * whole file has a golden, and actionlint checks it when it is installed.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+  { name: "app", dependsOn: ["net"], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] },
+];
+
+const GOLDEN = join(import.meta.dirname, "__fixtures__", "pr-loop.github.golden.yml");
+
+function hasActionlint(): boolean {
+  try {
+    execFileSync("actionlint", ["-version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface Step {
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+}
+interface Job {
+  if: string;
+  permissions: Record<string, string>;
+  concurrency?: Record<string, unknown>;
+  steps: Step[];
+}
+
+describe("the GitHub pull-request workflow", () => {
+  const result = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} });
+  const doc = parseYAML(result.yaml) as { name: string; on: Record<string, unknown>; jobs: Record<string, Job> };
+
+  test("matches its golden", () => {
+    if (process.env.UPDATE_GOLDEN) writeFileSync(GOLDEN, result.yaml);
+    expect(result.yaml).toBe(readFileSync(GOLDEN, "utf-8"));
+  });
+
+  test("plans on a pull request into main and applies on a push to it", () => {
+    expect(doc.name).toBe("chant-pr-prod");
+    expect(doc.on).toEqual({ pull_request: { branches: ["main"] }, push: { branches: ["main"] } });
+    expect(doc.jobs.plan.if).toBe("github.event_name == 'pull_request'");
+    expect(doc.jobs.apply.if).toBe("github.event_name == 'push'");
+    expect(result.jobs.map((j) => j.jobName)).toEqual(["plan", "apply"]);
+  });
+
+  test("the plan job measures from the pull request's base and cannot push; the apply job can, one at a time", () => {
+    const plan = doc.jobs.plan.steps.find((s) => s.run?.includes("pr-plan"))!;
+    expect(plan.run).toBe('chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github');
+    expect(plan.env).toMatchObject({ BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}" });
+    expect(doc.jobs.plan.permissions).toEqual({ contents: "read", "pull-requests": "write", statuses: "write" });
+
+    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("pr-apply"))!;
+    expect(apply.run).toContain("--require-review");
+    expect(apply.env).toMatchObject({ BASE_SHA: "${{ github.event.before }}" });
+    expect(doc.jobs.apply.permissions.contents).toBe("write");
+    expect(doc.jobs.apply.concurrency).toEqual({ group: "chant-apply-prod", "cancel-in-progress": false });
+    for (const job of Object.values(doc.jobs)) expect(job.steps[0].with).toEqual({ "fetch-depth": 0 });
+  });
+
+  test("the gate, branch and review requirement are options", () => {
+    const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { gate: "infra-apply", branch: "trunk", requireReview: false } }).yaml;
+    expect(yaml).toContain("--gate infra-apply");
+    expect(yaml).toContain("- trunk");
+    expect(yaml).not.toContain("--require-review");
+  });
+
+  test("refuses a wave or promote job beside it", () => {
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g" } })).toThrow(/pull-request pipeline has no wave or promote jobs/);
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, promoteTo: "prod" })).toThrow(/pull-request pipeline has no wave or promote jobs/);
+  });
+
+  test.skipIf(!hasActionlint())("passes actionlint", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-actionlint-"));
+    try {
+      mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+      writeFileSync(join(dir, ".github", "workflows", "chant-pr.yml"), result.yaml);
+      expect(() => execFileSync("actionlint", [".github/workflows/chant-pr.yml"], { cwd: dir, encoding: "utf8" })).not.toThrow();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/composites/checkout.ts

@@ -1,5 +1,6 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Step } from "../generated/index";
+import { actionRef, type ActionPinMode } from "../action-pins";
 
 export interface CheckoutProps {
   ref?: string;
@@ -8,6 +9,12 @@ export interface CheckoutProps {
   token?: string;
   submodules?: boolean | string;
   sshKey?: string;
+  /**
+   * `"tag"` (default) emits the action's major tag. `"sha"` emits the commit
+   * SHA from the lexicon's pin table with the version as a YAML comment, which
+   * passes GHA021, GHA029 and GHA059.
+   */
+  pin?: ActionPinMode;
   defaults?: {
     step?: Partial<ConstructorParameters<typeof Step>[0]>;
   };
@@ -25,7 +32,7 @@ export const Checkout = Composite((props: CheckoutProps) => {
 
   const step = new Step(mergeDefaults({
     name: "Checkout",
-    uses: "actions/checkout@v4",
+    uses: actionRef("actions/checkout", props.pin),
     ...(Object.keys(withObj).length > 0 ? { with: withObj } : {}),
   }, defaults?.step));
 

package/src/composites/composites.test.ts

@@ -19,7 +19,7 @@ describe("Checkout", () => {
   test("returns step with checkout action", () => {
     const result = Checkout({});
     expect(result.step).toBeDefined();
-    expect(result.step.props.uses).toBe("actions/checkout@v4");
+    expect(result.step.props.uses).toBe("actions/checkout@v7");
     expect(result.step.props.name).toBe("Checkout");
   });
 
@@ -45,7 +45,7 @@ describe("Checkout", () => {
 describe("SetupNode", () => {
   test("returns step with setup-node action", () => {
     const result = SetupNode({});
-    expect(result.step.props.uses).toBe("actions/setup-node@v4");
+    expect(result.step.props.uses).toBe("actions/setup-node@v7");
     expect(result.step.props.name).toBe("Setup Node.js");
   });
 
@@ -540,7 +540,7 @@ describe("DeployEnvironment", () => {
     const result = DeployEnvironment({ name: "staging", deployScript: "npm run deploy" });
     const steps = result.deployJob.props.steps as Array<{ props: Record<string, unknown> }>;
     expect(steps.length).toBe(2);
-    expect(steps[0].props.uses).toBe("actions/checkout@v4");
+    expect(steps[0].props.uses).toBe("actions/checkout@v7");
     expect(steps[1].props.run).toBe("npm run deploy");
   });
 
@@ -683,7 +683,7 @@ describe("defaults overrides", () => {
       defaults: { step: { id: "my-checkout" } },
     });
     expect(result.step.props.id).toBe("my-checkout");
-    expect(result.step.props.uses).toBe("actions/checkout@v4");
+    expect(result.step.props.uses).toBe("actions/checkout@v7");
   });
 
   test("SetupNode defaults override step props", () => {

package/src/composites/deploy-environment.ts

@@ -1,5 +1,6 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Job, Step } from "../generated/index";
+import { actionRef } from "../action-pins";
 
 export interface DeployEnvironmentProps {
   /** Environment name. Required. */
@@ -40,7 +41,7 @@ export const DeployEnvironment = Composite((props: DeployEnvironmentProps) => {
 
   // ── Deploy job ─────────────────────────────────────────────────────
   const deploySteps = [
-    new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+    new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
     ...deployScriptArr.map(
       (cmd: string) => new Step({ name: "Deploy", run: cmd }),
     ),
@@ -63,7 +64,7 @@ export const DeployEnvironment = Composite((props: DeployEnvironmentProps) => {
 
   // ── Cleanup job ────────────────────────────────────────────────────
   const cleanupSteps = [
-    new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+    new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
     ...cleanupScriptArr.map(
       (cmd: string) => new Step({ name: "Cleanup", run: cmd }),
     ),

package/src/composites/docker-build.ts

@@ -1,5 +1,6 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Job, Step, Workflow } from "../generated/index";
+import { actionRef } from "../action-pins";
 
 export interface DockerBuildProps {
   /** Image tag. Default: "${{ github.sha }}" */
@@ -44,7 +45,7 @@ export const DockerBuild = Composite((props: DockerBuildProps) => {
   } = props;
 
   // ── Steps ──────────────────────────────────────────────────────────
-  const checkout = new Step({ name: "Checkout", uses: "actions/checkout@v4" });
+  const checkout = new Step({ name: "Checkout", uses: actionRef("actions/checkout") });
 
   const login = new Step({
     name: "Log in to container registry",

package/src/composites/go-ci.ts

@@ -1,5 +1,6 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Job, Step, Workflow } from "../generated/index";
+import { actionRef } from "../action-pins";
 
 export interface GoCIProps {
   /** Go version. Default: "1.22" */
@@ -34,7 +35,7 @@ export const GoCI = Composite((props: GoCIProps) => {
   const buildJob = new Job(mergeDefaults({
     "runs-on": runsOn,
     steps: [
-      new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+      new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
       new Step({
         name: "Setup Go",
         uses: "actions/setup-go@v5",
@@ -48,7 +49,7 @@ export const GoCI = Composite((props: GoCIProps) => {
   const testJob = new Job(mergeDefaults({
     "runs-on": runsOn,
     steps: [
-      new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+      new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
       new Step({
         name: "Setup Go",
         uses: "actions/setup-go@v5",
@@ -64,7 +65,7 @@ export const GoCI = Composite((props: GoCIProps) => {
       ? new Job(mergeDefaults({
           "runs-on": runsOn,
           steps: [
-            new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+            new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
             new Step({
               name: "Setup Go",
               uses: "actions/setup-go@v5",