@intentius/chant-lexicon-github 0.124.46 → 0.124.49

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

@@ -0,0 +1,68 @@
+/**
+ * The pull-request workflow with `ci.locks: plan` (#4327): a lock job after
+ * the plan runs `chant lock --from-report` and an unlock job runs `chant
+ * unlock` when the pull request closes. Both check out the target branch's
+ * commit. Without the option the workflow is unchanged.
+ */
+
+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" }] }] },
+];
+
+interface Step { name?: string; uses?: string; run?: string; env?: Record<string, string>; with?: Record<string, unknown> }
+interface Job { if?: string; needs?: string[]; permissions: Record<string, string>; steps: Step[] }
+type Doc = { on: Record<string, unknown>; jobs: Record<string, Job> };
+
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("the GitHub workflow with ci.locks: plan", () => {
+  const doc = gen({ locks: "plan" });
+
+  test("adds a lock job and an unlock job, and fires on close", () => {
+    expect(Object.keys(doc.jobs)).toEqual(["plan", "plan-note", "lock", "unlock", "record"]);
+    expect(doc.on.pull_request).toEqual({ branches: ["main"], types: ["opened", "synchronize", "reopened", "closed"] });
+    expect(doc.jobs.plan!.if).toBe("github.event_name == 'pull_request' && github.event.action != 'closed'");
+  });
+
+  test("the lock job needs the plan, takes its report and runs chant lock --from-report from the base commit", () => {
+    const job = doc.jobs.lock!;
+    expect(job.needs).toEqual(["plan"]);
+    expect(job.steps[0]!.with!.ref).toBe("${{ github.event.pull_request.base.sha }}");
+    expect(job.steps.some((s) => s.run?.includes("needs.plan.outputs"))).toBe(true);
+    const lock = job.steps.find((s) => s.run?.startsWith("chant lock"))!;
+    expect(lock.run).toBe('chant lock --from-report .chant/pr/pr-plan.json --pr "$PR_NUMBER" --head "$HEAD_SHA" --stage plan --forge github');
+    expect(lock.env!.PR_NUMBER).toBe("${{ github.event.pull_request.number }}");
+    expect(job.permissions).toEqual({ contents: "write", "pull-requests": "read", statuses: "write" });
+  });
+
+  test("the unlock job runs chant unlock on close, from the base commit, and runs no head code", () => {
+    const job = doc.jobs.unlock!;
+    expect(job.if).toBe("github.event_name == 'pull_request' && github.event.action == 'closed'");
+    expect(job.steps[0]!.with!.ref).toBe("${{ github.event.pull_request.base.sha }}");
+    expect(job.steps.find((s) => s.run?.startsWith("chant unlock"))!.run).toBe('chant unlock --pr "$PR_NUMBER"');
+  });
+
+  test("without ci.locks the workflow has neither job and fires on the default pull request types", () => {
+    const plain = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} }).yaml;
+    expect(parseYAML(plain)).toMatchObject({ on: { pull_request: { branches: ["main"] } } });
+    expect(plain).not.toContain("closed");
+    expect(plain).not.toContain("chant lock");
+    expect(plain).not.toContain("chant unlock");
+  });
+});
+
+describe("with a pull request environment too", () => {
+  test("the pull_request types and the plan condition are the same as with the environment alone", () => {
+    const both = gen({ locks: "plan", prEnvironment: true });
+    const env = gen({ prEnvironment: true });
+    expect(both.on.pull_request).toEqual(env.on.pull_request);
+    expect(both.jobs.plan!.if).toBe(env.jobs.plan!.if);
+    expect(Object.keys(both.jobs)).toContain("lock");
+    expect(Object.keys(both.jobs)).toContain("env-down");
+  });
+});

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

@@ -14,6 +14,7 @@ import type { DriverComponent } from "@intentius/chant/components/driver";
 import { githubBaseFallback, greenCheckout, prApplyGroup, prApplyRecordKey, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
 import { dropForgeTokens } from "@intentius/chant/ci-handover";
 import { generateGithubPipeline } from "./generate-pipeline";
+import { ACTION_PINS, usesRef } from "@intentius/chant/action-pins";
 
 const ESTATE: DriverComponent[] = [
   { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
@@ -80,7 +81,8 @@ describe("the GitHub pull-request workflow", () => {
     expect(lastLine(plan.run)).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
     expect(plan.env).toMatchObject({ BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}" });
     // The runner key is an optional secret: unset, the expression is empty and the record is unsigned.
-    expect(plan.env?.CHANT_RUNNER_KEY).toBe("${{ secrets.CHANT_RUNNER_KEY }}");
+    // #4328: the plan runs the pull request's code, so its job never gets the runner key.
+    expect(plan.env?.CHANT_RUNNER_KEY).toBeUndefined();
     // #4295: the plan job only reads; the plan-note job writes the note and the status.
     expect(doc.jobs.plan.permissions).toEqual({ contents: "read" });
     expect(doc.jobs["plan-note"].permissions).toEqual({ actions: "read", contents: "read", "pull-requests": "write", statuses: "write" });
@@ -123,9 +125,9 @@ describe("the GitHub pull-request workflow", () => {
 
   test("the apply resumes from a record the cache keeps for the pushed commit across a re-run (#3543)", () => {
     const steps = doc.jobs.apply.steps;
-    const restore = steps.findIndex((s) => s.uses === "actions/cache/restore@v4");
+    const restore = steps.findIndex((s) => s.uses === `${usesRef(ACTION_PINS.cacheRestore4)}`);
     const run = steps.findIndex((s) => s.run?.includes("ci run apply"));
-    const save = steps.findIndex((s) => s.uses === "actions/cache/save@v4");
+    const save = steps.findIndex((s) => s.uses === `${usesRef(ACTION_PINS.cacheSave4)}`);
     expect(restore).toBeGreaterThan(-1);
     expect(restore).toBeLessThan(run);
     expect(save).toBeGreaterThan(run);
@@ -199,7 +201,7 @@ describe("the GitHub pull-request workflow", () => {
     expect(mdoc.jobs.apply.concurrency).toEqual({ group: "chant-apply.network.prod", "cancel-in-progress": false });
     // The record path is relative to the member for --resume and to the repository for the cache.
     expect(apply.run).toContain("--in-place");
-    const restore = mdoc.jobs.apply.steps.find((s) => s.uses === "actions/cache/restore@v4")!;
+    const restore = mdoc.jobs.apply.steps.find((s) => s.uses === `${usesRef(ACTION_PINS.cacheRestore4)}`)!;
     expect(restore.with).toMatchObject({ path: "infra/network/.chant/pr-resume/pr-apply.json", "restore-keys": "chant-apply.network.prod-${{ github.sha }}-" });
     // #4295: the plan job uploads nothing; the plan-note job keeps its report.
     expect(mdoc.jobs.plan.steps.some((s) => s.uses?.startsWith("actions/upload-artifact"))).toBe(false);

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

@@ -14,6 +14,7 @@ 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";
+import { ACTION_PINS, usesRef } from "@intentius/chant/action-pins";
 
 const root = (name: string, dependsOn: string[] = []): DriverComponent => ({
   name,
@@ -112,8 +113,8 @@ describe("the GitHub pull-request workflow with a gate per wave (#4003)", () =>
   test("each wave restores the commit's newest record and saves its own, so wave k reads what wave k-1 left", () => {
     for (const k of [1, 2, 3]) {
       const steps = doc.jobs[`apply-wave-${k}`]!.steps;
-      const restore = steps.find((s) => s.uses === "actions/cache/restore@v4")!;
-      const save = steps.find((s) => s.uses === "actions/cache/save@v4")!;
+      const restore = steps.find((s) => s.uses === `${usesRef(ACTION_PINS.cacheRestore4)}`)!;
+      const save = steps.find((s) => s.uses === `${usesRef(ACTION_PINS.cacheSave4)}`)!;
       const key = `chant-apply-prod-\${{ github.sha }}-\${{ github.run_id }}-\${{ github.run_attempt }}-wave-${k}`;
       expect(restore.with).toEqual({ path: ".chant/pr-resume/pr-apply.json", key, "restore-keys": "chant-apply-prod-${{ github.sha }}-" });
       expect(save).toMatchObject({ if: "always()", with: { path: ".chant/pr-resume/pr-apply.json", key } });

package/src/components/review-jobs.ts

@@ -0,0 +1,165 @@
+/**
+ * The two jobs of a split review (#4326): `ScheduledOpSpec.reviewAgent`.
+ *
+ * An Op that runs a `reviewAgent` step in `handoff` mode runs the change's
+ * code (`chant run` loads the pull request's Op files) beside a model. This
+ * generator keeps the forge write token out of that job and posts the note
+ * from another one, as terragucci's review does (`render-review.ts`: the
+ * `review` and `review-note` jobs):
+ *
+ * - the review job holds `contents: read` and no forge token in any step's
+ *   environment, bar the checkout script's fetches (`checkoutScript`,
+ *   ../../../../packages/core/src/ci-handover.ts). Every later step starts
+ *   without the token variables (`dropForgeTokens`). The `chant run` step is
+ *   its last, and it hands the review directory on as the job's outputs
+ *   (`handoverTrap`), in place of an artifact upload that would start beside
+ *   whatever the change's code left running.
+ * - the note job checks nothing out. It takes the outputs back as data
+ *   (`takeOverScript`), installs the chant release this lexicon belongs to
+ *   and runs `postReviewNote` with the job's token. The Op's name comes from
+ *   this file, not from the review, which the change's code wrote.
+ *
+ * Forgejo's runner ignores `permissions:` and may put its token in a step's
+ * environment, so the review job drops the token variables on both forges.
+ */
+
+import { readFileSync } from "node:fs";
+import { GITHUB_JOB_TOKEN, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
+import type { OpTrigger, PipelineMember } from "@intentius/chant/lexicon";
+
+/** The variable `reviewAgent` reads its handoff directory from (`REVIEW_DIR_ENV`, review-agent.ts). */
+const REVIEW_DIR_ENV = "CHANT_REVIEW_DIR";
+
+/** Where the review job writes the review, from the directory the step starts in. */
+const REVIEW_DIR = ".chant/review";
+
+/** The id of the review job's `chant run` step, which its outputs come from. */
+const REVIEW_STEP_ID = "chant-review";
+
+/** The name of the note job beside the Op's own job. */
+export function reviewNoteJobName(jobName: string): string {
+  return `${jobName}-note`;
+}
+
+/**
+ * Refuse a spec whose review cannot be split the way this shape needs:
+ * a trigger with no pull request to post on, a finding-mode that would give
+ * the review job a write scope, or an additive scope that would.
+ */
+export function assertReviewSplit(name: string, trigger: OpTrigger, findingMode: string, permissions: Record<string, string> | undefined): void {
+  if (trigger.kind !== "pull_request") {
+    throw new Error(
+      `Scheduled Op "${name}" sets reviewAgent, which posts the review as a note on the pull request that triggered the run, but its trigger is "${trigger.kind}". Give it a { kind: "pull_request" } trigger.`,
+    );
+  }
+  if (findingMode !== "report") {
+    throw new Error(
+      `Scheduled Op "${name}" sets reviewAgent with findingMode "${findingMode}". The review job holds no forge write token, and the note job posts instead, so the Op's own finding-mode must be "report".`,
+    );
+  }
+  for (const [scope, level] of Object.entries(permissions ?? {})) {
+    if (level === "write" && scope !== "id-token") {
+      throw new Error(
+        `Scheduled Op "${name}" sets reviewAgent and adds the permission "${scope}: write". The review job runs the change's code and may hold only "id-token: write" beyond contents: read.`,
+      );
+    }
+  }
+}
+
+/** The chant release the note job installs: this lexicon's own, which releases in lockstep with `@intentius/chant`. */
+function chantVersion(): string {
+  const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version?: unknown };
+  if (typeof pkg.version !== "string" || pkg.version === "") {
+    throw new Error("the github lexicon's package.json has no version to pin the review note job's chant to");
+  }
+  return pkg.version;
+}
+
+/** What the note job runs under node: `postReviewNote` over the review the review job handed on. Plain JavaScript, no `${{ }}`. */
+const NOTE_SCRIPT = [
+  'import { postReviewNote } from "@intentius/chant/op/activities/review-agent";',
+  `const { CHANT_OP: op, ${REVIEW_DIR_ENV}: dir } = process.env;`,
+  "const result = await postReviewNote({ op, dir });",
+  "console.log(result.reason);",
+  "if (!result.posted) process.exitCode = 1;",
+].join("\n");
+
+/** Where the note job puts the review it took back: outside any checkout, which it has none of. */
+const NOTE_DIR = '"${RUNNER_TEMP:-/tmp}/chant-review"';
+
+/** The note step's shell: install the pinned chant beside the review and run {@link NOTE_SCRIPT} with tsx. */
+function noteScript(version: string): string {
+  return [
+    `review=${NOTE_DIR}`,
+    'dir="${RUNNER_TEMP:-/tmp}/chant-review-note"',
+    'mkdir -p "$dir"',
+    'cd "$dir"',
+    "echo '{\"private\":true}' > package.json",
+    `npm install --omit=peer --no-audit --no-fund --loglevel=error @intentius/chant@${version}`,
+    "cat > note.mjs <<'NOTE'",
+    NOTE_SCRIPT,
+    "NOTE",
+    `${REVIEW_DIR_ENV}="$review" node --import tsx note.mjs`,
+  ].join("\n");
+}
+
+export interface ReviewJobsInput {
+  /** The Op's name: what `chant run` targets and what keys the note. */
+  name: string;
+  /** The Op's job name. */
+  jobName: string;
+  image: string;
+  /** The invocation of the Op, `chant run <name>` by default. */
+  invocation: string;
+  /** Setup steps, as built by `setupStepDoc`. */
+  setup: Array<Record<string, unknown>>;
+  beforeScript: readonly string[];
+  extraScript: readonly string[];
+  /** The Op's own per-job environment (`ScheduledOpSpec.variables`). */
+  variables?: Record<string, string>;
+  member?: PipelineMember;
+}
+
+/** The review job and the note job of one split review. */
+export function reviewJobs(i: ReviewJobsInput): { review: Record<string, unknown>; note: Record<string, unknown> } {
+  const drop = dropForgeTokens("sh");
+  const rooted = !i.member || i.member.dir === "." || i.member.dir === "";
+  const headStep = (line: string): Record<string, unknown> => ({ run: `${drop}\n${line}` });
+  const review = {
+    "runs-on": GITHUB_RUNNER,
+    container: i.image,
+    ...(i.variables && Object.keys(i.variables).length > 0 ? { env: i.variables } : {}),
+    outputs: handoverOutputs(REVIEW_STEP_ID, "github"),
+    steps: [
+      // A script, not actions/checkout: the token reaches the fetches alone, and the base branch's history comes with them for the diff.
+      {
+        name: "Check out the change",
+        ...(rooted ? {} : { "working-directory": "." }),
+        env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
+        run: checkoutScript(true),
+      },
+      ...i.setup,
+      ...i.beforeScript.map(headStep),
+      // The job's last step: it hands the review directory on as the job's outputs when it ends, however it ends.
+      {
+        id: REVIEW_STEP_ID,
+        name: "Run the Op and keep its review",
+        env: { [REVIEW_DIR_ENV]: REVIEW_DIR },
+        run: [drop, ...handoverTrap(REVIEW_DIR, "github"), i.invocation, ...i.extraScript].join("\n"),
+      },
+    ],
+  };
+  const note = {
+    needs: i.jobName,
+    if: `needs.${i.jobName}.result == 'success'`,
+    "runs-on": GITHUB_RUNNER,
+    container: i.image,
+    permissions: { "pull-requests": "write" },
+    steps: [
+      { name: "Take the review from the review job", run: takeOverScript(i.jobName, NOTE_DIR, "github") },
+      { name: "Post the review as a note", env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN, CHANT_OP: i.name }, run: noteScript(chantVersion()) },
+    ],
+  };
+  return { review, note };
+}

package/src/composites/cache.ts

@@ -1,4 +1,5 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
+import { actionRef } from "../action-pins";
 import { Step } from "../generated/index";
 
 export interface CacheActionProps {
@@ -20,7 +21,7 @@ export const CacheAction = Composite((props: CacheActionProps) => {
 
   const step = new Step(mergeDefaults({
     name: "Cache",
-    uses: "actions/cache@v4",
+    uses: actionRef("actions/cache"),
     with: withObj,
   }, defaults?.step));
 

package/src/composites/checkout.ts

@@ -10,9 +10,9 @@ export interface CheckoutProps {
   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.
+   * `"sha"` (default) emits the commit SHA from the pin table with the version as
+   * a YAML comment, which passes GHA021, GHA029 and GHA059. `"tag"` emits the
+   * action's major tag.
    */
   pin?: ActionPinMode;
   defaults?: {
@@ -32,7 +32,7 @@ export const Checkout = Composite((props: CheckoutProps) => {
 
   const step = new Step(mergeDefaults({
     name: "Checkout",
-    uses: actionRef("actions/checkout", props.pin),
+    uses: actionRef("actions/checkout", props.pin ?? "sha"),
     ...(Object.keys(withObj).length > 0 ? { with: withObj } : {}),
   }, defaults?.step));
 

package/src/composites/composites.test.ts

@@ -1,4 +1,5 @@
 import { describe, test, expect } from "vitest";
+import { actionRef, type PinnedAction } from "../action-pins";
 import { Checkout } from "./checkout";
 import { SetupNode } from "./setup-node";
 import { SetupGo } from "./setup-go";
@@ -22,7 +23,7 @@ describe("Checkout", () => {
   test("returns step with checkout action", () => {
     const result = Checkout({});
     expect(result.step).toBeDefined();
-    expect(propsOf(result.step).uses).toBe("actions/checkout@v7");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/checkout" as PinnedAction));
     expect(propsOf(result.step).name).toBe("Checkout");
   });
 
@@ -48,7 +49,7 @@ describe("Checkout", () => {
 describe("SetupNode", () => {
   test("returns step with setup-node action", () => {
     const result = SetupNode({});
-    expect(propsOf(result.step).uses).toBe("actions/setup-node@v7");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/setup-node" as PinnedAction));
     expect(propsOf(result.step).name).toBe("Setup Node.js");
   });
 
@@ -68,7 +69,7 @@ describe("SetupNode", () => {
 describe("SetupGo", () => {
   test("returns step with setup-go action", () => {
     const result = SetupGo({});
-    expect(propsOf(result.step).uses).toBe("actions/setup-go@v5");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/setup-go" as PinnedAction));
   });
 
   test("passes goVersion", () => {
@@ -82,7 +83,7 @@ describe("SetupGo", () => {
 describe("SetupPython", () => {
   test("returns step with setup-python action", () => {
     const result = SetupPython({});
-    expect(propsOf(result.step).uses).toBe("actions/setup-python@v5");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/setup-python" as PinnedAction));
   });
 
   test("passes pythonVersion", () => {
@@ -96,7 +97,7 @@ describe("SetupPython", () => {
 describe("CacheAction", () => {
   test("returns step with cache action", () => {
     const result = CacheAction({ path: "node_modules", key: "npm-${{ hashFiles('package-lock.json') }}" });
-    expect(propsOf(result.step).uses).toBe("actions/cache@v4");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/cache" as PinnedAction));
     expect((propsOf(result.step).with as Record<string, string>).path).toBe("node_modules");
     expect((propsOf(result.step).with as Record<string, string>).key).toBe("npm-${{ hashFiles('package-lock.json') }}");
   });
@@ -107,7 +108,7 @@ describe("CacheAction", () => {
 describe("UploadArtifact", () => {
   test("returns step with upload action", () => {
     const result = UploadArtifact({ name: "build", path: "dist/" });
-    expect(propsOf(result.step).uses).toBe("actions/upload-artifact@v4");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/upload-artifact" as PinnedAction));
     expect((propsOf(result.step).with as Record<string, string>).name).toBe("build");
     expect((propsOf(result.step).with as Record<string, string>).path).toBe("dist/");
   });
@@ -123,7 +124,7 @@ describe("UploadArtifact", () => {
 describe("DownloadArtifact", () => {
   test("returns step with download action", () => {
     const result = DownloadArtifact({ name: "build" });
-    expect(propsOf(result.step).uses).toBe("actions/download-artifact@v4");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/download-artifact" as PinnedAction));
     expect((propsOf(result.step).with as Record<string, string>).name).toBe("build");
   });
 });
@@ -228,7 +229,7 @@ describe("NodePipeline", () => {
   test("bun uses oven-sh/setup-bun instead of setup-node", () => {
     const result = NodePipeline({ packageManager: "bun" });
     const steps = propsOf(result.buildJob).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[1].props.uses).toBe("oven-sh/setup-bun@v2");
+    expect(steps[1].props.uses).toBe(actionRef("oven-sh/setup-bun" as PinnedAction));
     expect(steps[1].props.name).toBe("Setup Bun");
   });
 
@@ -247,14 +248,14 @@ describe("NodePipeline", () => {
   test("upload step uses upload-artifact with configured name", () => {
     const result = NodePipeline({ artifactName: "my-build" });
     const steps = propsOf(result.buildJob).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[4].props.uses).toBe("actions/upload-artifact@v4");
+    expect(steps[4].props.uses).toBe(actionRef("actions/upload-artifact" as PinnedAction));
     expect((steps[4].props.with as Record<string, string>).name).toBe("my-build");
   });
 
   test("download step in testJob uses configured artifact name", () => {
     const result = NodePipeline({ artifactName: "my-build" });
     const steps = propsOf(result.testJob).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[3].props.uses).toBe("actions/download-artifact@v4");
+    expect(steps[3].props.uses).toBe(actionRef("actions/download-artifact" as PinnedAction));
     expect((steps[3].props.with as Record<string, string>).name).toBe("my-build");
   });
 
@@ -289,7 +290,7 @@ describe("BunPipeline", () => {
   test("defaults to bun package manager", () => {
     const result = BunPipeline({});
     const steps = propsOf(result.buildJob).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[1].props.uses).toBe("oven-sh/setup-bun@v2");
+    expect(steps[1].props.uses).toBe(actionRef("oven-sh/setup-bun" as PinnedAction));
     expect(steps[2].props.run).toBe("bun install --frozen-lockfile");
   });
 });
@@ -340,7 +341,7 @@ describe("PythonCI", () => {
     const result = PythonCI({});
     const steps = propsOf(result.testJob).steps as Array<{ props: Record<string, unknown> }>;
     const setupStep = steps[1];
-    expect(propsOf(setupStep).uses).toBe("actions/setup-python@v5");
+    expect(propsOf(setupStep).uses).toBe(actionRef("actions/setup-python" as PinnedAction));
     expect((propsOf(setupStep).with as Record<string, string>)["python-version"]).toBe("3.12");
   });
 
@@ -430,25 +431,25 @@ describe("DockerBuild", () => {
   test("uses docker/login-action", () => {
     const result = DockerBuild({});
     const steps = propsOf(result.job).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[1].props.uses).toBe("docker/login-action@v3");
+    expect(steps[1].props.uses).toBe(actionRef("docker/login-action" as PinnedAction));
   });
 
   test("uses docker/setup-buildx-action", () => {
     const result = DockerBuild({});
     const steps = propsOf(result.job).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[2].props.uses).toBe("docker/setup-buildx-action@v3");
+    expect(steps[2].props.uses).toBe(actionRef("docker/setup-buildx-action" as PinnedAction));
   });
 
   test("uses docker/metadata-action", () => {
     const result = DockerBuild({});
     const steps = propsOf(result.job).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[3].props.uses).toBe("docker/metadata-action@v5");
+    expect(steps[3].props.uses).toBe(actionRef("docker/metadata-action" as PinnedAction));
   });
 
   test("uses docker/build-push-action", () => {
     const result = DockerBuild({});
     const steps = propsOf(result.job).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[4].props.uses).toBe("docker/build-push-action@v6");
+    expect(steps[4].props.uses).toBe(actionRef("docker/build-push-action" as PinnedAction));
   });
 
   test("login step uses ghcr.io by default", () => {
@@ -543,7 +544,7 @@ describe("DeployEnvironment", () => {
     const result = DeployEnvironment({ name: "staging", deployScript: "npm run deploy" });
     const steps = propsOf(result.deployJob).steps as Array<{ props: Record<string, unknown> }>;
     expect(steps.length).toBe(2);
-    expect(steps[0].props.uses).toBe("actions/checkout@v7");
+    expect(steps[0].props.uses).toBe(actionRef("actions/checkout" as PinnedAction));
     expect(steps[1].props.run).toBe("npm run deploy");
   });
 
@@ -630,7 +631,7 @@ describe("GoCI", () => {
   test("buildJob uses setup-go with default version", () => {
     const result = GoCI({});
     const steps = propsOf(result.buildJob).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[1].props.uses).toBe("actions/setup-go@v5");
+    expect(steps[1].props.uses).toBe(actionRef("actions/setup-go" as PinnedAction));
     expect((steps[1].props.with as Record<string, string>)["go-version"]).toBe("1.22");
   });
 
@@ -667,7 +668,7 @@ describe("GoCI", () => {
   test("lintJob uses golangci-lint-action", () => {
     const result = GoCI({});
     const steps = propsOf(result.lintJob!).steps as Array<{ props: Record<string, unknown> }>;
-    expect(steps[2].props.uses).toBe("golangci/golangci-lint-action@v6");
+    expect(steps[2].props.uses).toBe(actionRef("golangci/golangci-lint-action" as PinnedAction));
   });
 
   test("uses custom runsOn", () => {
@@ -686,7 +687,7 @@ describe("defaults overrides", () => {
       defaults: { step: { id: "my-checkout" } },
     });
     expect(propsOf(result.step).id).toBe("my-checkout");
-    expect(propsOf(result.step).uses).toBe("actions/checkout@v7");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/checkout" as PinnedAction));
   });
 
   test("SetupNode defaults override step props", () => {
@@ -769,7 +770,7 @@ describe("defaults overrides", () => {
       defaults: { step: { id: "upload" } },
     });
     expect(propsOf(result.step).id).toBe("upload");
-    expect(propsOf(result.step).uses).toBe("actions/upload-artifact@v4");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/upload-artifact" as PinnedAction));
   });
 
   test("CacheAction defaults override step props", () => {
@@ -779,6 +780,6 @@ describe("defaults overrides", () => {
       defaults: { step: { id: "cache-step" } },
     });
     expect(propsOf(result.step).id).toBe("cache-step");
-    expect(propsOf(result.step).uses).toBe("actions/cache@v4");
+    expect(propsOf(result.step).uses).toBe(actionRef("actions/cache" as PinnedAction));
   });
 });

package/src/composites/docker-build.ts

@@ -49,7 +49,7 @@ export const DockerBuild = Composite((props: DockerBuildProps) => {
 
   const login = new Step({
     name: "Log in to container registry",
-    uses: "docker/login-action@v3",
+    uses: actionRef("docker/login-action"),
     with: {
       registry,
       username: "${{ github.actor }}",
@@ -59,7 +59,7 @@ export const DockerBuild = Composite((props: DockerBuildProps) => {
 
   const setupBuildx = new Step({
     name: "Set up Docker Buildx",
-    uses: "docker/setup-buildx-action@v3",
+    uses: actionRef("docker/setup-buildx-action"),
   });
 
   // Build tags for metadata action
@@ -71,7 +71,7 @@ export const DockerBuild = Composite((props: DockerBuildProps) => {
   const metadata = new Step({
     name: "Extract metadata",
     id: "meta",
-    uses: "docker/metadata-action@v5",
+    uses: actionRef("docker/metadata-action"),
     with: {
       images: imageName,
       tags: tags.join("\n"),
@@ -98,7 +98,7 @@ export const DockerBuild = Composite((props: DockerBuildProps) => {
 
   const buildPush = new Step({
     name: "Build and push",
-    uses: "docker/build-push-action@v6",
+    uses: actionRef("docker/build-push-action"),
     with: buildPushWith,
   });
 

package/src/composites/download-artifact.ts

@@ -1,4 +1,5 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
+import { actionRef } from "../action-pins";
 import { Step } from "../generated/index";
 
 export interface DownloadArtifactProps {
@@ -19,7 +20,7 @@ export const DownloadArtifact = Composite((props: DownloadArtifactProps) => {
 
   const step = new Step(mergeDefaults({
     name: "Download Artifact",
-    uses: "actions/download-artifact@v4",
+    uses: actionRef("actions/download-artifact"),
     ...(Object.keys(withObj).length > 0 ? { with: withObj } : {}),
   }, defaults?.step));
 

package/src/composites/go-ci.ts

@@ -38,7 +38,7 @@ export const GoCI = Composite((props: GoCIProps) => {
       new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
       new Step({
         name: "Setup Go",
-        uses: "actions/setup-go@v5",
+        uses: actionRef("actions/setup-go"),
         with: { "go-version": goVersion },
       }),
       new Step({ name: "Build", run: buildCommand }),
@@ -52,7 +52,7 @@ export const GoCI = Composite((props: GoCIProps) => {
       new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
       new Step({
         name: "Setup Go",
-        uses: "actions/setup-go@v5",
+        uses: actionRef("actions/setup-go"),
         with: { "go-version": goVersion },
       }),
       new Step({ name: "Test", run: testCommand }),
@@ -68,12 +68,12 @@ export const GoCI = Composite((props: GoCIProps) => {
             new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
             new Step({
               name: "Setup Go",
-              uses: "actions/setup-go@v5",
+              uses: actionRef("actions/setup-go"),
               with: { "go-version": goVersion },
             }),
             new Step({
               name: "Lint",
-              uses: "golangci/golangci-lint-action@v6",
+              uses: actionRef("golangci/golangci-lint-action"),
               with: { args: lintCommand },
             }),
           ],

package/src/composites/node-pipeline.ts

@@ -51,7 +51,7 @@ const cacheConfig = {
     cache: undefined,
     installCmd: "bun install --frozen-lockfile",
     runPrefix: "bun run",
-    setupAction: "oven-sh/setup-bun@v2",
+    setupAction: actionRef("oven-sh/setup-bun"),
   },
 } as const;
 
@@ -79,7 +79,7 @@ export const NodePipeline = Composite((props: NodePipelineProps) => {
   const buildCheckout = new Step({ name: "Checkout", uses: actionRef("actions/checkout") });
 
   const buildSetup = isBun
-    ? new Step({ name: "Setup Bun", uses: "oven-sh/setup-bun@v2" })
+    ? new Step({ name: "Setup Bun", uses: actionRef("oven-sh/setup-bun") })
     : new Step({
         name: "Setup Node.js",
         uses: actionRef("actions/setup-node"),
@@ -92,7 +92,7 @@ export const NodePipeline = Composite((props: NodePipelineProps) => {
 
   const buildUpload = new Step({
     name: "Upload build artifacts",
-    uses: "actions/upload-artifact@v4",
+    uses: actionRef("actions/upload-artifact"),
     with: {
       name: artifactName,
       path: buildArtifactPaths.join("\n"),
@@ -109,7 +109,7 @@ export const NodePipeline = Composite((props: NodePipelineProps) => {
   const testCheckout = new Step({ name: "Checkout", uses: actionRef("actions/checkout") });
 
   const testSetup = isBun
-    ? new Step({ name: "Setup Bun", uses: "oven-sh/setup-bun@v2" })
+    ? new Step({ name: "Setup Bun", uses: actionRef("oven-sh/setup-bun") })
     : new Step({
         name: "Setup Node.js",
         uses: actionRef("actions/setup-node"),
@@ -120,7 +120,7 @@ export const NodePipeline = Composite((props: NodePipelineProps) => {
 
   const testDownload = new Step({
     name: "Download build artifacts",
-    uses: "actions/download-artifact@v4",
+    uses: actionRef("actions/download-artifact"),
     with: { name: artifactName },
   });