@intentius/chant-lexicon-github 0.101.0 → 0.104.0

package/src/lint/post-synth/gha069.test.ts

@@ -0,0 +1,173 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha069 } from "./gha069";
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures", "GHA069");
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+function fixture(name: string): PostSynthContext {
+  return makeCtx(readFileSync(join(FIXTURES, `${name}.yml`), "utf-8"));
+}
+
+/** The issue's fixture with the workflow block, the job block and the step swapped in. */
+function workflow(opts: { wf?: string; job?: string; step: string }): string {
+  const wf = opts.wf ?? "permissions:\n  id-token: write\n  contents: read\n";
+  const job = opts.job === undefined ? "" : `    permissions: ${opts.job}\n`;
+  return `name: Deploy
+on:
+  push:
+${wf}jobs:
+  deploy:
+    runs-on: ubuntu-latest
+${job}    steps:
+${opts.step}`;
+}
+
+const AWS_STEP = `      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/deploy
+          aws-region: us-east-1
+`;
+
+describe("GHA069: job-level permissions block drops the workflow's id-token: write", () => {
+  test("fires on the issue's fixture and names the scope, the job and the fix", () => {
+    const diags = gha069.check(fixture("positive"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA069");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("deploy");
+    expect(diags[0].message).toContain("id-token: write");
+    expect(diags[0].message).toContain('Job "deploy"');
+    expect(diags[0].message).toContain("aws-actions/configure-aws-credentials");
+    expect(diags[0].message).toContain("Add `id-token: write` to job \"deploy\"'s permissions block");
+    expect(diags[0].message).toContain("rather than removing it");
+  });
+
+  test("does not fire when the job block carries the scope", () => {
+    expect(gha069.check(fixture("negative"))).toHaveLength(0);
+  });
+
+  test("does not fire when there is no job-level block", () => {
+    expect(gha069.check(fixture("negative-no-job-block"))).toHaveLength(0);
+  });
+
+  test("does not fire on a job block whose job needs no OIDC token", () => {
+    expect(gha069.check(fixture("negative-no-oidc-step"))).toHaveLength(0);
+  });
+
+  test("does not fire when the workflow block never granted id-token", () => {
+    const yaml = workflow({ wf: "permissions:\n  contents: read\n", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("does not fire when there is no workflow block at all", () => {
+    const yaml = workflow({ wf: "", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test.each([
+    ["azure/login", "azure/login@v2", "client-id: abc"],
+    ["Azure/login, as usually written", "Azure/login@v2", "client-id: abc"],
+    ["google-github-actions/auth", "google-github-actions/auth@v2", "workload_identity_provider: projects/1/locations/global/workloadIdentityPools/p/providers/gh"],
+    [
+      "a full SHA pin with a version comment",
+      "aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2",
+      "role-to-assume: arn:aws:iam::123456789012:role/deploy",
+    ],
+    ["a major-only ref", "aws-actions/configure-aws-credentials@v4", "role-to-assume: arn:aws:iam::123456789012:role/deploy"],
+    ["an exact tag", "aws-actions/configure-aws-credentials@v4.0.2", "role-to-assume: arn:aws:iam::123456789012:role/deploy"],
+  ])("matches %s on the action path whatever the ref", (_label, uses, input) => {
+    const step = `      - uses: ${uses}\n        with:\n          ${input}\n`;
+    const diags = gha069.check(makeCtx(workflow({ job: "\n      contents: read\n", step })));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("a job block of {} drops id-token too", () => {
+    const diags = gha069.check(makeCtx(workflow({ job: "{}", step: AWS_STEP })));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("`permissions: {}`");
+  });
+
+  test("a job block of read-all drops id-token too", () => {
+    const diags = gha069.check(makeCtx(workflow({ job: "read-all", step: AWS_STEP })));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("`permissions: read-all`");
+  });
+
+  test("a job block of write-all grants id-token, so it does not fire", () => {
+    expect(gha069.check(makeCtx(workflow({ job: "write-all", step: AWS_STEP })))).toHaveLength(0);
+  });
+
+  test("a workflow block of write-all grants id-token, so a narrower job block drops it", () => {
+    const yaml = workflow({ wf: "permissions: write-all\n", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(1);
+  });
+
+  test("a workflow block of read-all never granted id-token, so it does not fire", () => {
+    const yaml = workflow({ wf: "permissions: read-all\n", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("a job block setting id-token: none still drops it", () => {
+    const diags = gha069.check(makeCtx(workflow({ job: "\n      id-token: none\n", step: AWS_STEP })));
+    expect(diags).toHaveLength(1);
+  });
+
+  test.each([
+    ["aws-actions/configure-aws-credentials@v4", "aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}"],
+    ["azure/login@v2", "creds: ${{ secrets.AZURE_CREDENTIALS }}"],
+    ["google-github-actions/auth@v2", "credentials_json: ${{ secrets.GCP_SA_KEY }}"],
+  ])("does not fire when %s is given a static credential", (uses, input) => {
+    const step = `      - uses: ${uses}\n        with:\n          ${input}\n`;
+    expect(gha069.check(makeCtx(workflow({ job: "\n      contents: read\n", step })))).toHaveLength(0);
+  });
+
+  test("reports each affected job once, and only those", () => {
+    const yaml = `name: Deploy
+on: push
+permissions:
+  id-token: write
+jobs:
+  staging:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/staging
+      - uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: projects/1/locations/global/workloadIdentityPools/p/providers/gh
+  prod:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/prod
+`;
+    const diags = gha069.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("staging");
+    expect(diags[0].message).toContain("aws-actions/configure-aws-credentials, google-github-actions/auth");
+  });
+});

package/src/lint/post-synth/gha069.ts

@@ -0,0 +1,111 @@
+/**
+ * GHA069: Job-Level Permissions Block Drops the Workflow's `id-token: write`
+ *
+ * A job-level `permissions:` block replaces the workflow-level one; GitHub
+ * does not merge the two. A workflow that grants `id-token: write` at the top
+ * and then gives a job its own block without that scope leaves the job with
+ * no OIDC token, and the job's cloud-credential action fails with an error
+ * that names neither the scope nor the job block (#2273).
+ *
+ * Fires when all three hold:
+ * - the workflow-level block grants `id-token: write` (directly, or through
+ *   `write-all`);
+ * - a job declares its own block that does not (a map without
+ *   `id-token: write`, `{}`, `read-all`, or any other preset but `write-all`);
+ * - that job has a step using a known OIDC credential action, matched on the
+ *   action path whatever the ref (tag, major or full SHA), with no static
+ *   credential input that would make the step skip OIDC.
+ *
+ * Only `id-token` is checked. The reasoning for not generalising to every
+ * scope a job block narrows is recorded on #2273.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  getPrimaryOutput,
+  extractWorkflowPermissions,
+  extractJobPermissions,
+  extractStepsByJob,
+  parseActionUses,
+  type PermissionsValue,
+} from "./yaml-helpers";
+
+/**
+ * Actions that exchange the job's OIDC token for cloud credentials, keyed by
+ * lowercased `owner/repo`, each with the inputs that select a static
+ * credential instead (when one is set, the step does not need `id-token`).
+ */
+export const OIDC_CREDENTIAL_ACTIONS: ReadonlyMap<string, readonly string[]> = new Map([
+  ["aws-actions/configure-aws-credentials", ["aws-access-key-id", "web-identity-token-file"]],
+  ["azure/login", ["creds"]],
+  ["google-github-actions/auth", ["credentials_json"]],
+]);
+
+/** True when the permissions value grants `id-token: write`. */
+export function grantsIdTokenWrite(perms: PermissionsValue): boolean {
+  if (typeof perms === "string") return perms.trim() === "write-all";
+  return perms["id-token"] === "write";
+}
+
+/** The OIDC credential action a step uses, as written, or undefined. */
+function oidcActionOf(step: Record<string, unknown>): string | undefined {
+  if (typeof step.uses !== "string") return undefined;
+  const parsed = parseActionUses(step.uses);
+  if (!parsed) return undefined;
+  const staticInputs = OIDC_CREDENTIAL_ACTIONS.get(parsed.slug.toLowerCase());
+  if (!staticInputs) return undefined;
+  const withInputs = step.with;
+  if (withInputs && typeof withInputs === "object" && !Array.isArray(withInputs)) {
+    const inputs = withInputs as Record<string, unknown>;
+    if (staticInputs.some((k) => inputs[k] !== undefined && inputs[k] !== null && inputs[k] !== "")) return undefined;
+  }
+  return parsed.slug;
+}
+
+function describeJobBlock(perms: PermissionsValue): string {
+  if (typeof perms === "string") return `\`permissions: ${perms}\``;
+  if (Object.keys(perms).length === 0) return "`permissions: {}`";
+  return "its own `permissions:` block";
+}
+
+export const gha069: PostSynthCheck = {
+  id: "GHA069",
+  description: "Job-level permissions block drops the workflow's id-token: write that an OIDC credential step needs",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const wf = extractWorkflowPermissions(yaml);
+      if (!wf || !grantsIdTokenWrite(wf)) continue;
+
+      const jobPermissions = extractJobPermissions(yaml);
+      if (jobPermissions.size === 0) continue;
+
+      const stepsByJob = extractStepsByJob(yaml);
+      for (const [job, perms] of jobPermissions) {
+        if (grantsIdTokenWrite(perms)) continue;
+
+        const actions = [
+          ...new Set((stepsByJob.get(job) ?? []).map(oidcActionOf).filter((a): a is string => a !== undefined)),
+        ];
+        if (actions.length === 0) continue;
+
+        diagnostics.push({
+          checkId: "GHA069",
+          severity: "warning",
+          message:
+            `Job "${job}" declares ${describeJobBlock(perms)}, which replaces the workflow-level block instead of merging with it, ` +
+            `so the workflow's \`id-token: write\` does not reach the job and ${actions.join(", ")} cannot request an OIDC token. ` +
+            `Add \`id-token: write\` to job "${job}"'s permissions block; keep the job block rather than removing it.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/index.ts

@@ -55,6 +55,7 @@ import { gha065 } from "./gha065";
 import { gha066 } from "./gha066";
 import { gha067 } from "./gha067";
 import { gha068 } from "./gha068";
+import { gha069 } from "./gha069";
 
 export const postSynthChecks: PostSynthCheck[] = [
   gha006,
@@ -112,4 +113,5 @@ export const postSynthChecks: PostSynthCheck[] = [
   gha066,
   gha067,
   gha068,
+  gha069,
 ];

package/src/lint/post-synth/yaml-helpers.test.ts

@@ -0,0 +1,83 @@
+import { describe, test, expect } from "vitest";
+import { extractJobs, buildNeedsGraph } from "./yaml-helpers";
+
+// The shape chant's serializer emits: every step starts with `name:`, and
+// `run:` is often a block scalar. The line-based extractJobs read only the
+// first line of a job's first step, so it saw none of these steps (#3201).
+const NAME_FIRST = `name: CI
+on:
+  pull_request_target:
+    branches:
+      - main
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7 # v7.0.1
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+      - name: Test
+        run: |
+          npm ci
+          npm test
+  Publish_Docs:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Publish
+        run: echo publish
+  deploy:
+    needs:
+      - build
+      - Publish_Docs
+    runs-on: ubuntu-latest
+    steps:
+      - id: go
+        name: Deploy
+        run: echo deploy
+`;
+
+describe("extractJobs (#3201)", () => {
+  test("reads every step of a job whose steps start with name:", () => {
+    const build = extractJobs(NAME_FIRST).get("build");
+    expect(build?.steps).toEqual([
+      { name: "Checkout", uses: "actions/checkout@v7", run: undefined },
+      { name: "Setup Node", uses: "actions/setup-node@v7", run: undefined },
+      { name: "Test", uses: undefined, run: "npm ci\nnpm test\n" },
+    ]);
+  });
+
+  test("reads a step whose first key is neither name, uses nor run", () => {
+    expect(extractJobs(NAME_FIRST).get("deploy")?.steps).toEqual([
+      { name: "Deploy", uses: undefined, run: "echo deploy" },
+    ]);
+  });
+
+  test("reads job ids with capitals and underscores", () => {
+    expect([...extractJobs(NAME_FIRST).keys()]).toEqual(["build", "Publish_Docs", "deploy"]);
+  });
+
+  test("reads needs as a scalar, a block list and a flow list", () => {
+    const jobs = extractJobs(NAME_FIRST);
+    expect(jobs.get("build")?.needs).toBeUndefined();
+    expect(jobs.get("Publish_Docs")?.needs).toEqual(["build"]);
+    expect(jobs.get("deploy")?.needs).toEqual(["build", "Publish_Docs"]);
+    expect(extractJobs(`jobs:\n  a:\n    needs: [x, "y"]\n    runs-on: ubuntu-latest\n`).get("a")?.needs).toEqual(["x", "y"]);
+  });
+
+  test("buildNeedsGraph sees scalar needs", () => {
+    expect(buildNeedsGraph(NAME_FIRST).get("Publish_Docs")).toEqual(["build"]);
+  });
+
+  test("a reusable-workflow job has no steps", () => {
+    const jobs = extractJobs(`jobs:\n  call:\n    uses: ./.github/workflows/x.yml\n`);
+    expect(jobs.get("call")).toEqual({ name: "call" });
+  });
+
+  test("unparseable YAML yields no jobs", () => {
+    expect(extractJobs("jobs:\n  a: [\n").size).toBe(0);
+  });
+});

package/src/lint/post-synth/yaml-helpers.ts

@@ -37,66 +37,45 @@ export interface ParsedJob {
 
 /**
  * Extract jobs from a serialized GitHub Actions workflow YAML.
+ *
+ * Built on the structural parser ({@link jobEntries}), so every step of every
+ * job is read whatever key the step starts with, and `needs:` is read in all
+ * three forms (a scalar, a flow list, a block list). The line-based version
+ * this replaced stopped after the first line of a job's first step, so a step
+ * that starts with `name:` (the shape chant's serializer emits) had no `uses:`
+ * or `run:` and later steps were never seen (#3201).
+ *
+ * `run` is the whole script, block scalars included. `permissions` is not
+ * filled here; use {@link extractJobPermissions}.
  */
 export function extractJobs(yaml: string): Map<string, ParsedJob> {
   const jobs = new Map<string, ParsedJob>();
-
-  // Find the jobs: section — take everything after `jobs:\n`
-  const jobsIdx = yaml.search(/^jobs:\s*$/m);
-  if (jobsIdx === -1) return jobs;
-
-  // Content after the `jobs:` line. Stop at the next top-level key (non-indented) or EOF.
-  const afterJobs = yaml.slice(jobsIdx + yaml.slice(jobsIdx).indexOf("\n") + 1);
-  const endMatch = afterJobs.search(/^[a-z]/m);
-  const jobsContent = endMatch === -1 ? afterJobs : afterJobs.slice(0, endMatch);
-
-  // Split into individual jobs by finding lines with exactly 2 spaces of indent followed by a key
-  const jobSections = jobsContent.split(/\n(?=  [a-z][a-z0-9-]*:)/);
-
-  for (const section of jobSections) {
-    const nameMatch = section.match(/^\s{2}([a-z][a-z0-9-]*):/);
-    if (!nameMatch) continue;
-
-    const name = nameMatch[1];
+  for (const [name, jobObj] of jobEntries(yaml)) {
     const job: ParsedJob = { name };
 
-    // Extract needs
-    const needsInline = section.match(/^\s{4}needs:\s+\[(.+)\]$/m);
-    if (needsInline) {
-      job.needs = needsInline[1].split(",").map((s) => s.trim().replace(/^'|'$/g, "").replace(/^"|"$/g, ""));
-    } else {
-      const needsList = section.match(/^\s{4}needs:\n((?:\s{6}- .+\n?)+)/m);
-      if (needsList) {
-        job.needs = [];
-        for (const line of needsList[1].split("\n")) {
-          const item = line.match(/^\s{6}- (.+)$/);
-          if (item) job.needs.push(item[1].trim().replace(/^'|'$/g, "").replace(/^"|"$/g, ""));
-        }
-      }
+    const needs = jobObj.needs;
+    if (typeof needs === "string") {
+      job.needs = [needs];
+    } else if (Array.isArray(needs)) {
+      job.needs = needs.filter((n) => typeof n === "string" || typeof n === "number").map(String);
     }
 
-    // Extract steps with uses:
-    const stepsMatch = section.match(/^\s{4}steps:\n([\s\S]*?)(?=\n\s{4}[a-z]|\n\s{2}[a-z]|$)/m);
-    if (stepsMatch) {
+    const steps = jobObj.steps;
+    if (Array.isArray(steps)) {
       job.steps = [];
-      const stepEntries = stepsMatch[1].split(/\n(?=\s{6}- )/);
-      for (const stepEntry of stepEntries) {
-        const usesMatch = stepEntry.match(/uses:\s+(.+)$/m);
-        const runMatch = stepEntry.match(/run:\s+(.+)$/m);
-        const stepNameMatch = stepEntry.match(/name:\s+(.+)$/m);
-        if (usesMatch || runMatch) {
-          job.steps.push({
-            uses: usesMatch?.[1] ? stripUsesComment(usesMatch[1].trim().replace(/^'|'$/g, "")) : undefined,
-            run: runMatch?.[1]?.trim(),
-            name: stepNameMatch?.[1]?.trim().replace(/^'|'$/g, ""),
-          });
-        }
+      for (const raw of steps) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+        const step = raw as Record<string, unknown>;
+        job.steps.push({
+          uses: typeof step.uses === "string" ? stripUsesComment(step.uses) : undefined,
+          run: typeof step.run === "string" ? step.run : undefined,
+          name: typeof step.name === "string" ? step.name : undefined,
+        });
       }
     }
 
     jobs.set(name, job);
   }
-
   return jobs;
 }
 
@@ -497,6 +476,21 @@ export function extractUsesComment(rawUses: string): string | undefined {
   return comment ? comment : undefined;
 }
 
+/**
+ * Every `uses:` line in the workflow text, in document order, with its
+ * trailing comment. The parsed document has no comments (core's parseYAML
+ * drops them, #3006), so a check that reads the pin label (GHA059) takes it
+ * from here.
+ */
+export function usesLineComments(yaml: string): Array<{ ref: string; comment: string | undefined }> {
+  const out: Array<{ ref: string; comment: string | undefined }> = [];
+  for (const line of yaml.split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:-\s+)?uses:\s*(["']?)([^\s"'#]+)\1(\s+#.*)?\s*$/);
+    if (m) out.push({ ref: m[2], comment: m[3] ? extractUsesComment(m[3]) : undefined });
+  }
+  return out;
+}
+
 export function parseActionUses(rawUses: string): { owner: string; repo: string; slug: string; gitRef: string } | undefined {
   const uses = stripUsesComment(rawUses);
   if (uses.startsWith("./") || uses.startsWith("../") || uses.startsWith("docker://")) return undefined;

package/src/lint/rules/data/deprecated-versions.ts

@@ -2,9 +2,12 @@
  * Deprecated action versions and recommended replacements.
  */
 
+import { ACTION_PINS } from "../../../action-pins";
+
 export const deprecatedVersions: Record<string, { deprecated: string[]; recommended: string }> = {
-  "actions/checkout": { deprecated: ["v1", "v2", "v3"], recommended: "v4" },
-  "actions/setup-node": { deprecated: ["v1", "v2", "v3"], recommended: "v4" },
+  // v4 runs on Node 20, which GitHub has deprecated for actions.
+  "actions/checkout": { deprecated: ["v1", "v2", "v3", "v4"], recommended: ACTION_PINS["actions/checkout"].major },
+  "actions/setup-node": { deprecated: ["v1", "v2", "v3", "v4"], recommended: ACTION_PINS["actions/setup-node"].major },
   "actions/setup-go": { deprecated: ["v1", "v2", "v3", "v4"], recommended: "v5" },
   "actions/setup-python": { deprecated: ["v1", "v2", "v3", "v4"], recommended: "v5" },
   "actions/cache": { deprecated: ["v1", "v2", "v3"], recommended: "v4" },

package/src/lint/rules/deprecated-action-version.test.ts

@@ -19,7 +19,7 @@ describe("GHA012: deprecated-action-version", () => {
   });
 
   test("does not flag current version", () => {
-    const ctx = createContext(`const s = "actions/checkout@v4";`);
+    const ctx = createContext(`const s = "actions/checkout@v7";`);
     const diags = deprecatedActionVersionRule.check(ctx);
     expect(diags).toHaveLength(0);
   });

package/src/lint/rules/rules.test.ts

@@ -244,7 +244,7 @@ describe("GHA012: deprecated-action-version", () => {
   });
 
   test("does not flag current version", () => {
-    const ctx = createContext(`const s = "actions/checkout@v4";`);
+    const ctx = createContext(`const s = "actions/checkout@v7";`);
     const diags = deprecatedActionVersionRule.check(ctx);
     expect(diags).toHaveLength(0);
   });

package/src/mcp/context-tools.test.ts

@@ -33,6 +33,23 @@ describe("downstreamJobs / actionPinned (#327)", () => {
     expect(downstreamJobs(yaml, "deploy")).toEqual([]);
   });
 
+  test("downstreamJobs follows a scalar needs: (#3201)", () => {
+    const yaml = `jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: echo build
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Test
+        run: echo test
+`;
+    expect(downstreamJobs(yaml, "build")).toEqual(["test"]);
+  });
+
   test("actionPinned only accepts a full commit SHA", () => {
     expect(actionPinned("actions/checkout@" + "a".repeat(40))).toBe(true);
     expect(actionPinned("actions/checkout@v4")).toBe(false);

package/src/plugin.test.ts

@@ -24,7 +24,7 @@ describe("githubPlugin", () => {
 
   test("provides post-synth checks", () => {
     const checks = githubPlugin.postSynthChecks!();
-    expect(checks.length).toBe(55);
+    expect(checks.length).toBe(56);
 
     const checkIds = checks.map((c) => c.id);
     expect(checkIds).toContain("GHA006");

package/src/serializer.ts

@@ -12,7 +12,7 @@ import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
-import { emitYAML } from "@intentius/chant/yaml";
+import { emitYAMLEntry } from "@intentius/chant/yaml";
 
 // ── Key conversion ────────────────────────────────────────────────
 
@@ -459,7 +459,7 @@ function emitYAMLDocument(doc: Record<string, unknown>): string {
       } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         sections.push(`${key}: ${yamlScalar(value)}`);
       } else {
-        sections.push(`${key}:` + emitYAML(value, 1));
+        sections.push(emitYAMLEntry(key, value));
       }
     }
   }
@@ -470,11 +470,22 @@ function emitYAMLDocument(doc: Record<string, unknown>): string {
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
       sections.push(`${key}: ${yamlScalar(value)}`);
     } else {
-      sections.push(`${key}:` + emitYAML(value, 1));
+      sections.push(emitYAMLEntry(key, value));
     }
   }
 
-  return sections.join("\n\n") + "\n";
+  return unquotePinComments(sections.join("\n\n") + "\n");
+}
+
+/**
+ * A SHA-pinned `uses:` carries its version as a trailing comment
+ * (`actions/checkout@<sha> # v7.0.1`). The YAML emitter quotes any string with
+ * a `#`, which would make the comment part of the ref GitHub resolves. A ref
+ * holds no whitespace, so `<ref> # <label>` inside quotes is always this
+ * pattern, and writing it unquoted turns the label back into a comment.
+ */
+function unquotePinComments(yaml: string): string {
+  return yaml.replace(/^(\s*(?:- )?uses: )'([^\s']+) # ([^'\n]*)'$/gm, "$1$2 # $3");
 }
 
 function yamlScalar(value: string | number | boolean): string {