@intentius/chant-lexicon-github 0.1.22 → 0.2.0

package/src/codegen/docs.ts

@@ -952,6 +952,12 @@ Flags matrix strategy dimensions with an empty values array. An empty dimension
 
 Flags jobs whose \`needs:\` entries reference a job not defined in the workflow. This causes a workflow validation error on GitHub.
 
+### GHA013 — Missing job-level permissions for sensitive triggers
+
+**Severity:** warning
+
+Flags jobs without an explicit \`permissions:\` block when the workflow uses a sensitive trigger (\`pull_request_target\` or \`workflow_dispatch\`). Declaring job-level permissions keeps least-privilege scope on workflows that run with elevated context.
+
 ### GHA017 — Missing permissions block
 
 **Severity:** info
@@ -970,6 +976,188 @@ Flags workflows triggered by \`pull_request_target\` that include \`actions/chec
 
 Detects cycles in the \`needs:\` dependency graph. If job A needs B and B needs A (directly or transitively), GitHub rejects the workflow. Reports the full cycle chain in the diagnostic message.
 
+### GHA029 — Action or reusable workflow not pinned to a commit SHA
+
+**Severity:** warning
+
+Flags any \`uses:\` — step action or job-level reusable workflow — pinned to a mutable tag or branch instead of a full commit SHA. Tags can be repointed to malicious code after review, so every external reference should be pinned. \`actions/checkout\` is covered by the more specific GHA021; local (\`./\`) and \`docker://\` references are out of scope. Owners in the vendored trusted allowlist are exempt.
+
+### GHA030 — Container image not pinned to a digest
+
+**Severity:** warning
+
+Flags job \`container:\` images, \`services:\` images, and \`docker://\` step references that are not pinned to an immutable \`@sha256:\` digest. A mutable tag can be repointed to a different image after review.
+
+### GHA031 — Action resembles a well-known action
+
+**Severity:** warning
+
+Flags a \`uses:\` slug that is a near-miss (edit distance 1–2) of a popular action but not an exact match — a likely typo or impersonation under different ownership. Advisory; backed by a vendored reference list.
+
+### GHA032 — Archived or compromised action
+
+**Severity:** warning
+
+Flags a \`uses:\` slug that a vendored snapshot marks as archived/abandoned or carrying a disclosed security issue, with remediation. Advisory and necessarily incomplete.
+
+### GHA033 — Blanket write-all permissions
+
+**Severity:** warning
+
+Flags \`permissions: write-all\` at the workflow or job level. It grants the \`GITHUB_TOKEN\` every write scope regardless of need — replace it with the specific scopes the job uses.
+
+### GHA034 — Write permissions granted workflow-wide
+
+**Severity:** warning
+
+Flags individual write scopes declared at the workflow level, which apply to every job even when only one needs them. Move each write scope onto the specific job that uses it. (The \`write-all\` preset is covered by GHA033.)
+
+### GHA035 — Elevated scope on an untrusted-code trigger
+
+**Severity:** error
+
+Flags a workflow that grants the token write access while using a trigger that can run untrusted code (\`pull_request_target\`, \`workflow_run\`). An injected step would run with standing write credentials — drop the write scope or isolate the privileged work in a separate trusted workflow.
+
+### GHA036 — Untrusted input in a run: command
+
+**Severity:** error
+
+Flags an attacker-controllable expression context (PR title, branch name, issue/comment body, commit message) interpolated directly into a \`run:\` script — a script-injection sink. Pass the value through an \`env:\` variable and reference it quoted instead.
+
+### GHA037 — Untrusted input written to GITHUB_ENV / GITHUB_PATH
+
+**Severity:** error
+
+Flags a \`run:\` step that writes untrusted input into \`$GITHUB_ENV\` or \`$GITHUB_PATH\`, which set environment/PATH state for later steps and can escalate into takeover of a subsequent privileged step.
+
+### GHA038 — workflow_run trigger checking out untrusted code
+
+**Severity:** warning
+
+Generalizes GHA018 to the \`workflow_run\` trigger, which runs with repo write scope and secrets. Checking out the head/artifact of the triggering run pulls untrusted code into that privileged context.
+
+### GHA039 — Authorization gate on a spoofable identity
+
+**Severity:** warning
+
+Flags an \`if:\` condition that gates on a commit-author identity field (\`author.name\` / \`author.email\`). Those come from git metadata the committer sets freely and can be spoofed — gate on a verified signal (environment protection, CODEOWNERS, verified actor).
+
+### GHA040 — Self-hosted runner on an untrusted-code trigger
+
+**Severity:** warning
+
+Flags a job on a self-hosted runner under a trigger a fork can reach (\`pull_request\`, \`pull_request_target\`, \`workflow_run\`). Self-hosted runners are non-ephemeral and shared, so untrusted code can persist and compromise later jobs.
+
+### GHA041 — Blanket secrets: inherit into a reusable workflow
+
+**Severity:** warning
+
+Flags a reusable-workflow call passing \`secrets: inherit\`, which hands the called workflow every caller secret. Pass through only the specific secrets it needs.
+
+### GHA042 — Entire secrets context passed
+
+**Severity:** warning
+
+Flags \`toJSON(secrets)\` passed into a step or reusable workflow, serializing every secret where one or two specific references would do.
+
+### GHA043 — Secret consumed without an environment gate
+
+**Severity:** warning
+
+Extends GHA026: when a workflow gates some jobs with an \`environment:\`, flags the specific secret-using jobs that have none — the inconsistent-gating case where a job skips the approval/scoping applied elsewhere.
+
+### GHA044 — Hardcoded registry/container credential
+
+**Severity:** error
+
+Flags a \`password:\` / \`token:\` / \`registry-password:\` set to a literal rather than a \`\${{ secrets.* }}\` reference. Move the credential into a secret.
+
+### GHA045 — Secret interpolated into a run: command
+
+**Severity:** warning
+
+Flags \`\${{ secrets.* }}\` expanded directly into a \`run:\` script, where a transform can defeat log masking and the raw value is exposed to argument injection. Pass it through an \`env:\` variable and reference \`"$VAR"\` quoted.
+
+### GHA046 — Logically unsound guard condition
+
+**Severity:** warning
+
+Flags an \`if:\` condition that reads like a gate but evaluates to a constant — \`true\`/\`false\` literals, an \`X == X\` tautology, or a collapse via \`|| true\` / \`&& false\`. A gate that constrains nothing is misleading.
+
+### GHA047 — Ineffective contains() guard
+
+**Severity:** warning
+
+Flags \`contains('literal', <dynamic>)\` — a constant haystack with a dynamic needle. \`contains(search, item)\` tests whether \`item\` is in \`search\`, so reversed arguments make the result depend on a fixed string. Swap them.
+
+### GHA048 — Obfuscated guard condition
+
+**Severity:** warning
+
+Flags an \`if:\` gate whose compared operand is built through \`format()\` / \`join()\` / \`fromJSON()\` indirection. Constructing the operand at evaluation time hides what the gate checks — compare against the value directly.
+
+### GHA049 — Persisted checkout credentials reachable by an artifact
+
+**Severity:** warning
+
+Flags a job that checks out with persisted credentials (the default) and uploads an artifact — the token in \`.git/config\` can be swept into the artifact. Set \`persist-credentials: false\` on the checkout.
+
+### GHA050 — Cache populated in a privileged context
+
+**Severity:** warning
+
+Flags \`actions/cache\` under a privileged trigger (\`pull_request_target\`, \`workflow_run\`). A cache entry influenced by a fork can be restored and executed by a later trusted run (cache poisoning) — restrict caching to trusted triggers.
+
+### GHA051 — Publish step using a long-lived token instead of OIDC
+
+**Severity:** info
+
+Flags a publish/release job that uses a long-lived token secret while requesting no \`id-token: write\`. If the registry supports OIDC, mint a short-lived federated credential per run instead of holding a standing token.
+
+### GHA052 — Software fetched and piped to a shell
+
+**Severity:** warning
+
+Flags a \`run:\` step that pipes a network download straight into a shell (\`curl ... | bash\`). The fetched code is unpinned and unverified — download to a file, verify a checksum/signature, then run it.
+
+### GHA053 — Unsafe set-env / add-path opt-in
+
+**Severity:** error
+
+Flags re-enabling the \`set-env\` / \`add-path\` workflow commands removed for security (CVE-2020-15228) via \`ACTIONS_ALLOW_UNSECURE_COMMANDS\` or direct \`::set-env::\` / \`::add-path::\`. Use the \`$GITHUB_ENV\` / \`$GITHUB_PATH\` files instead.
+
+### GHA054 — Known-bad feature usage
+
+**Severity:** warning
+
+Catch-all, data-driven check flagging emitted content matching a vendored snapshot of risky features (deprecated workflow commands, unsafe runtime opt-ins). Advisory and necessarily incomplete.
+
+### GHA055 — Redundant runtime tool install
+
+**Severity:** info
+
+Flags a \`run:\` step that installs a tool GitHub-hosted runners already ship. The redundant install adds supply-chain surface for no benefit (irrelevant on self-hosted runners that may lack the tool).
+
+### GHA056 — Workflow without a name
+
+**Severity:** info
+
+Flags a workflow with no top-level \`name:\`. Without one, GitHub falls back to the file path in the UI and audit logs, making runs harder to identify.
+
+> Two items from issue #295 are intentionally not implemented at the post-synth layer: over-broad/unrevoked app-installation tokens (whether a minted token is scoped wider than used cannot be determined from emitted YAML) and a reference allowlist/denylist policy (configuration, overlapping the GHA029 trusted-owner allowlist).
+
+### GHA057 — Dependency update executes untrusted code
+
+**Severity:** error
+
+Flags a Dependabot \`updates:\` entry with \`insecure-external-code-execution: allow\`, which runs a freshly-pulled dependency's lifecycle scripts during the update itself — a compromised release executes before any review. Set it to \`deny\`. Requires the \`Dependabot\` resource so the config is emitted (\`.github/dependabot.yml\`).
+
+### GHA058 — Dependency update without a cooldown
+
+**Severity:** warning
+
+Flags a Dependabot \`updates:\` entry with no cooldown — a version published moments ago (including a compromised one) is adopted immediately. Configure a \`cooldown:\` window. The \`Dependabot\` composite ships a 7-day default.
+
 ## Running lint
 
 \`\`\`bash

package/src/composites/dependabot.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "vitest";
+import { Dependabot, DependabotConfig } from "./dependabot";
+import { githubSerializer } from "../serializer";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+describe("Dependabot composite (#294)", () => {
+  test("ships safe defaults: cooldown + external code execution denied", () => {
+    const cfg = Dependabot({ ecosystems: [{ packageEcosystem: "npm" }, { packageEcosystem: "github-actions" }] });
+    expect(cfg).toBeInstanceOf(DependabotConfig);
+    expect(cfg.props.version).toBe(2);
+    expect(cfg.props.updates).toHaveLength(2);
+    for (const u of cfg.props.updates) {
+      expect(u.cooldown?.defaultDays).toBe(7);
+      expect(u.insecureExternalCodeExecution).toBe("deny");
+      expect(u.directory).toBe("/");
+      expect(u.schedule.interval).toBe("weekly");
+    }
+  });
+
+  test("serializes to a .github/dependabot.yml file (kebab-case keys)", () => {
+    const cfg = Dependabot({ ecosystems: [{ packageEcosystem: "npm" }] });
+    const result = githubSerializer.serialize(new Map([["deps", cfg]])) as SerializerResult;
+    expect(typeof result).toBe("object");
+    const yaml = result.files?.["dependabot.yml"];
+    expect(yaml).toBeDefined();
+    expect(yaml).toContain("version: 2");
+    expect(yaml).toContain("package-ecosystem: npm");
+    expect(yaml).toContain("open-pull-requests-limit: 5");
+    expect(yaml).toContain("insecure-external-code-execution: deny");
+    expect(yaml).toContain("default-days: 7");
+  });
+
+  test("emits dependabot.yml alongside a workflow", () => {
+    const cfg = Dependabot({ ecosystems: [{ packageEcosystem: "pip", interval: "daily" }] });
+    const wf = {
+      [Symbol.for("chant.declarable")]: true,
+      lexicon: "github",
+      entityType: "GitHub::Actions::Workflow",
+      kind: "resource" as const,
+      props: { name: "CI" },
+    };
+    const result = githubSerializer.serialize(
+      new Map<string, never>([["ci", wf as never], ["deps", cfg as never]]),
+    ) as SerializerResult;
+    expect(result.primary).toContain("name: CI");
+    expect(result.files?.["dependabot.yml"]).toContain("package-ecosystem: pip");
+  });
+});

package/src/composites/dependabot.ts

@@ -0,0 +1,91 @@
+/**
+ * Dependency-update configuration (`.github/dependabot.yml`) as a chant
+ * resource, so it is emitted and lintable like workflows (#294).
+ *
+ * Two failure modes the post-synth checks target:
+ *   - an update that executes untrusted code from a freshly-pulled dependency
+ *     during the update itself (`insecure-external-code-execution: allow`), and
+ *   - a configuration with no cooldown — a version published seconds ago
+ *     (including a compromised one) is adopted before anyone can react.
+ *
+ * The `Dependabot` composite ships safe defaults: a cooldown window and an
+ * explicit deny on external code execution.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+
+/** A single `updates:` entry in dependabot.yml. */
+export interface DependabotUpdate {
+  /** e.g. "npm", "pip", "github-actions", "docker". */
+  packageEcosystem: string;
+  /** Directory to scan (defaults to "/"). */
+  directory?: string;
+  directories?: string[];
+  /** Update schedule. */
+  schedule: { interval: "daily" | "weekly" | "monthly"; day?: string; time?: string };
+  /** Cooldown window — delay adopting freshly-published versions. */
+  cooldown?: {
+    defaultDays?: number;
+    semverMajorDays?: number;
+    semverMinorDays?: number;
+    semverPatchDays?: number;
+  };
+  /** Cap on concurrent update PRs. */
+  openPullRequestsLimit?: number;
+  /** Whether to run a dependency's lifecycle scripts during the update. */
+  insecureExternalCodeExecution?: "allow" | "deny";
+  /** Passthrough for the rest of the dependabot update schema. */
+  [key: string]: unknown;
+}
+
+export interface DependabotConfigProps {
+  version?: number;
+  updates: DependabotUpdate[];
+  registries?: Record<string, unknown>;
+}
+
+/** The `.github/dependabot.yml` resource. */
+export class DependabotConfig implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "github";
+  readonly entityType = "GitHub::Dependabot::Config";
+  readonly kind = "resource" as const;
+  readonly props: DependabotConfigProps;
+
+  constructor(props: DependabotConfigProps) {
+    this.props = { version: 2, ...props };
+  }
+}
+
+export interface DependabotEcosystem {
+  packageEcosystem: string;
+  directory?: string;
+  interval?: "daily" | "weekly" | "monthly";
+}
+
+export interface DependabotProps {
+  /** Ecosystems to keep updated. */
+  ecosystems: DependabotEcosystem[];
+  /** Cooldown window in days before adopting a freshly-published version (default 7). */
+  cooldownDays?: number;
+  /** Cap on concurrent update PRs per ecosystem (default 5). */
+  openPullRequestsLimit?: number;
+}
+
+/**
+ * Build a `DependabotConfig` with safe defaults: a cooldown window on every
+ * ecosystem and external code execution explicitly denied.
+ */
+export function Dependabot(props: DependabotProps): DependabotConfig {
+  const cooldownDays = props.cooldownDays ?? 7;
+  const limit = props.openPullRequestsLimit ?? 5;
+  const updates: DependabotUpdate[] = props.ecosystems.map((e) => ({
+    packageEcosystem: e.packageEcosystem,
+    directory: e.directory ?? "/",
+    schedule: { interval: e.interval ?? "weekly" },
+    cooldown: { defaultDays: cooldownDays },
+    openPullRequestsLimit: limit,
+    insecureExternalCodeExecution: "deny",
+  }));
+  return new DependabotConfig({ version: 2, updates });
+}

package/src/composites/index.ts

@@ -24,3 +24,5 @@ export { DeployEnvironment } from "./deploy-environment";
 export type { DeployEnvironmentProps } from "./deploy-environment";
 export { GoCI } from "./go-ci";
 export type { GoCIProps } from "./go-ci";
+export { Dependabot, DependabotConfig } from "./dependabot";
+export type { DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem } from "./dependabot";

package/src/index.ts

@@ -30,6 +30,7 @@ export {
   DockerBuild,
   DeployEnvironment,
   GoCI,
+  Dependabot, DependabotConfig,
 } from "./composites/index";
 export type {
   CheckoutProps, SetupNodeProps, SetupGoProps, SetupPythonProps,
@@ -40,6 +41,7 @@ export type {
   DockerBuildProps,
   DeployEnvironmentProps,
   GoCIProps,
+  DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem,
 } from "./composites/index";
 
 // Spec utilities (for tooling)

package/src/lint/post-synth/{gha020.test.ts → gha013.test.ts}

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
-import { gha020 } from "./gha020";
+import { gha013 } from "./gha013";
 
 function makeCtx(yaml: string): PostSynthContext {
   return {
@@ -16,7 +16,7 @@ function makeCtx(yaml: string): PostSynthContext {
   };
 }
 
-describe("GHA020: missing job-level permissions for sensitive triggers", () => {
+describe("GHA013: missing job-level permissions for sensitive triggers", () => {
   test("flags job without permissions when using pull_request_target", () => {
     const yaml = `name: Review
 on:
@@ -27,9 +27,9 @@ jobs:
     steps:
       - run: echo review
 `;
-    const diags = gha020.check(makeCtx(yaml));
+    const diags = gha013.check(makeCtx(yaml));
     expect(diags).toHaveLength(1);
-    expect(diags[0].checkId).toBe("GHA020");
+    expect(diags[0].checkId).toBe("GHA013");
     expect(diags[0].severity).toBe("warning");
     expect(diags[0].message).toContain("review");
   });
@@ -44,9 +44,9 @@ jobs:
     steps:
       - run: echo deploy
 `;
-    const diags = gha020.check(makeCtx(yaml));
+    const diags = gha013.check(makeCtx(yaml));
     expect(diags).toHaveLength(1);
-    expect(diags[0].checkId).toBe("GHA020");
+    expect(diags[0].checkId).toBe("GHA013");
     expect(diags[0].message).toContain("deploy");
   });
 
@@ -60,7 +60,7 @@ jobs:
     steps:
       - run: echo build
 `;
-    const diags = gha020.check(makeCtx(yaml));
+    const diags = gha013.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
 });

package/src/lint/post-synth/{gha020.ts → gha013.ts}

@@ -1,5 +1,5 @@
 /**
- * GHA020: Missing Job-Level Permissions for Sensitive Triggers
+ * GHA013: Missing Job-Level Permissions for Sensitive Triggers
  *
  * Flags jobs without explicit `permissions:` when the workflow uses
  * `pull_request_target` or `workflow_dispatch` triggers.
@@ -8,8 +8,8 @@
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { getPrimaryOutput, extractJobs, extractTriggers } from "./yaml-helpers";
 
-export const gha020: PostSynthCheck = {
-  id: "GHA020",
+export const gha013: PostSynthCheck = {
+  id: "GHA013",
   description: "Missing job-level permissions for sensitive triggers",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
@@ -25,7 +25,7 @@ export const gha020: PostSynthCheck = {
       for (const [jobName, job] of jobs) {
         if (!job.permissions) {
           diagnostics.push({
-            checkId: "GHA020",
+            checkId: "GHA013",
             severity: "warning",
             message: `Job "${jobName}" lacks explicit permissions but workflow uses a sensitive trigger. Add job-level permissions for least-privilege security.`,
             entity: jobName,

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

@@ -0,0 +1,108 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha029, findUnpinnedActions } from "./gha029";
+
+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,
+    },
+  };
+}
+
+describe("GHA029: unpinned action / reusable workflow", () => {
+  test("flags a step action pinned to a tag", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+      - run: echo build
+`;
+    const diags = gha029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA029");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("build");
+    expect(diags[0].message).toContain("actions/setup-node@v4");
+  });
+
+  test("flags a job-level reusable workflow pinned to a tag", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  call:
+    uses: org/repo/.github/workflows/reusable.yml@v1
+`;
+    const diags = gha029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("reusable.yml@v1");
+  });
+
+  test("does not flag an action pinned to a full SHA", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
+      - run: echo build
+`;
+    const diags = gha029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag actions/checkout (owned by GHA021)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+`;
+    const diags = gha029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag local actions", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./.github/actions/local
+`;
+    const diags = gha029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("allowlist exempts a trusted owner", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: trustedco/action@v1
+`;
+    expect(findUnpinnedActions(yaml)).toHaveLength(1);
+    expect(findUnpinnedActions(yaml, new Set(["trustedco"]))).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,68 @@
+/**
+ * GHA029: Unpinned Action or Reusable-Workflow Reference
+ *
+ * Flags any `uses:` (step action or job-level reusable workflow) that is pinned
+ * to a mutable tag or branch instead of a full 40-character commit SHA. A tag
+ * can be repointed to malicious code after review, so every external reference
+ * is a supply-chain trust decision.
+ *
+ * `actions/checkout` is intentionally left to the more specific GHA021. Local
+ * references (`./`, `../`) and `docker://` images (GHA030) are out of scope.
+ * Owners in the trusted allowlist are exempt.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
+import { TRUSTED_ACTION_OWNERS } from "../rules/data/trusted-action-owners";
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+export interface UnpinnedRef {
+  job: string;
+  ref: string;
+  slug: string;
+}
+
+/**
+ * Find every action/reusable-workflow `uses:` that is not pinned to a commit
+ * SHA. Exposed as a pure function so the allowlist behaviour is testable.
+ */
+export function findUnpinnedActions(
+  yaml: string,
+  trustedOwners: ReadonlySet<string> = TRUSTED_ACTION_OWNERS,
+): UnpinnedRef[] {
+  const result: UnpinnedRef[] = [];
+  for (const { job, ref } of extractActionRefs(yaml)) {
+    const parsed = parseActionUses(ref);
+    if (!parsed) continue; // local or docker:// reference
+    if (parsed.slug === "actions/checkout") continue; // owned by GHA021
+    if (trustedOwners.has(parsed.owner)) continue;
+    if (SHA_RE.test(parsed.gitRef)) continue; // already pinned
+    result.push({ job, ref, slug: parsed.slug });
+  }
+  return result;
+}
+
+export const gha029: PostSynthCheck = {
+  id: "GHA029",
+  description: "Action or reusable workflow not pinned to a commit SHA",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, ref } of findUnpinnedActions(yaml)) {
+        diagnostics.push({
+          checkId: "GHA029",
+          severity: "warning",
+          message: `Job "${job}" uses ${ref} pinned to a tag or branch — pin to a full commit SHA for supply-chain security.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};