@intentius/chant-lexicon-github 0.1.23 → 0.2.0

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

@@ -2,8 +2,32 @@
  * Helpers for parsing serialized GitHub Actions YAML in post-synth checks.
  */
 
+import { parseYAML } from "@intentius/chant/yaml";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
 export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
 
+/**
+ * Return the emitted `.github/dependabot.yml` content from a serializer output,
+ * if present (it rides as an additional file alongside the workflow output).
+ */
+export function getDependabotYaml(output: string | SerializerResult): string | undefined {
+  if (typeof output === "string") return undefined;
+  return output.files?.["dependabot.yml"];
+}
+
+/** Parse the `updates:` array from a dependabot.yml document. */
+export function extractDependabotUpdates(dependabotYaml: string): Array<Record<string, unknown>> {
+  let doc: Record<string, unknown>;
+  try {
+    doc = parseYAML(dependabotYaml);
+  } catch {
+    return [];
+  }
+  const updates = doc.updates;
+  return Array.isArray(updates) ? (updates as Array<Record<string, unknown>>) : [];
+}
+
 export interface ParsedJob {
   name: string;
   needs?: string[];
@@ -127,3 +151,314 @@ export function extractWorkflowName(yaml: string): string | undefined {
 export function hasPermissions(yaml: string): boolean {
   return /^permissions:/m.test(yaml);
 }
+
+/** A single `uses:` reference found in a workflow. */
+export interface ActionRef {
+  /** Owning job name. */
+  job: string;
+  /** The raw `uses:` value (e.g. `actions/setup-node@v4`). */
+  ref: string;
+  /** Whether it is a step-level action or a job-level reusable workflow. */
+  level: "step" | "job";
+}
+
+/** A container/service/docker image reference found in a workflow. */
+export interface ImageRef {
+  /** Owning job name. */
+  job: string;
+  /** The raw image reference (e.g. `node:20`). */
+  image: string;
+  /** Where the image was declared. */
+  source: "container" | "service" | "step";
+}
+
+function parseDoc(yaml: string): Record<string, unknown> | undefined {
+  try {
+    return parseYAML(yaml);
+  } catch {
+    return undefined;
+  }
+}
+
+function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
+  const doc = parseDoc(yaml);
+  const jobs = doc?.jobs;
+  if (!jobs || typeof jobs !== "object") return [];
+  const out: Array<[string, Record<string, unknown>]> = [];
+  for (const [name, val] of Object.entries(jobs as Record<string, unknown>)) {
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      out.push([name, val as Record<string, unknown>]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract every `uses:` reference from the workflow — both step-level actions
+ * and job-level reusable-workflow calls. Uses the structural YAML parser so
+ * nested jobs/steps are handled reliably.
+ */
+export function extractActionRefs(yaml: string): ActionRef[] {
+  const refs: ActionRef[] = [];
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    if (typeof jobObj.uses === "string") {
+      refs.push({ job, ref: jobObj.uses, level: "job" });
+    }
+    const steps = jobObj.steps;
+    if (Array.isArray(steps)) {
+      for (const step of steps) {
+        if (step && typeof step === "object" && typeof (step as Record<string, unknown>).uses === "string") {
+          refs.push({ job, ref: (step as Record<string, unknown>).uses as string, level: "step" });
+        }
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * Extract every container/service/`docker://` image reference from the workflow.
+ */
+export function extractImageRefs(yaml: string): ImageRef[] {
+  const refs: ImageRef[] = [];
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    const container = jobObj.container;
+    if (typeof container === "string") {
+      refs.push({ job, image: container, source: "container" });
+    } else if (container && typeof container === "object" && typeof (container as Record<string, unknown>).image === "string") {
+      refs.push({ job, image: (container as Record<string, unknown>).image as string, source: "container" });
+    }
+
+    const services = jobObj.services;
+    if (services && typeof services === "object" && !Array.isArray(services)) {
+      for (const svc of Object.values(services as Record<string, unknown>)) {
+        if (typeof svc === "string") {
+          refs.push({ job, image: svc, source: "service" });
+        } else if (svc && typeof svc === "object" && typeof (svc as Record<string, unknown>).image === "string") {
+          refs.push({ job, image: (svc as Record<string, unknown>).image as string, source: "service" });
+        }
+      }
+    }
+
+    const steps = jobObj.steps;
+    if (Array.isArray(steps)) {
+      for (const step of steps) {
+        const uses = step && typeof step === "object" ? (step as Record<string, unknown>).uses : undefined;
+        if (typeof uses === "string" && uses.startsWith("docker://")) {
+          refs.push({ job, image: uses.slice("docker://".length), source: "step" });
+        }
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * Walk the `jobs:` block line-by-line, tracking the current job. Robust to `|`
+ * block scalars (which the structural parser does not handle), so it is the
+ * right tool for scanning `run:`/`if:`/`runs-on:` content.
+ */
+function scanJobLines(yaml: string, onLine: (job: string, line: string, indent: number, lineNo: number, lines: string[]) => void): void {
+  const lines = yaml.split("\n");
+  let inJobs = false;
+  let currentJob = "";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^jobs:\s*$/.test(line)) { inJobs = true; continue; }
+    if (!inJobs) continue;
+    if (/^\S/.test(line)) { inJobs = false; continue; } // dedented to a new top-level key
+    const jobHeader = line.match(/^ {2}([A-Za-z0-9_-]+):\s*$/);
+    if (jobHeader) { currentJob = jobHeader[1]; continue; }
+    if (!currentJob) continue;
+    const indent = line.search(/\S/);
+    if (indent < 0) continue;
+    onLine(currentJob, line, indent, i, lines);
+  }
+}
+
+/** A `run:` script block with its owning job. */
+export interface RunBlock {
+  job: string;
+  run: string;
+}
+
+/**
+ * Extract every `run:` script (inline and `|`/`>` block scalars) with its
+ * owning job.
+ */
+export function extractRunBlocks(yaml: string): RunBlock[] {
+  const out: RunBlock[] = [];
+  const consumed = new Set<number>();
+  scanJobLines(yaml, (job, line, _indent, lineNo, lines) => {
+    if (consumed.has(lineNo)) return;
+    const m = line.match(/^(\s*)(- )?run:\s*(.*)$/);
+    if (!m) return;
+    const keyIndent = m[1].length + (m[2] ? 2 : 0); // column where `run:` begins
+    const value = m[3].trim();
+    if (value === "|" || value === "|-" || value === ">" || value === ">-" || value === "|+" || value === ">+") {
+      const blockLines: string[] = [];
+      for (let j = lineNo + 1; j < lines.length; j++) {
+        const bl = lines[j];
+        if (bl.trim() === "") { blockLines.push(""); consumed.add(j); continue; }
+        const bi = bl.search(/\S/);
+        if (bi <= keyIndent) break;
+        blockLines.push(bl.trimStart());
+        consumed.add(j);
+      }
+      out.push({ job, run: blockLines.join("\n") });
+    } else {
+      out.push({ job, run: value.replace(/^['"]|['"]$/g, "") });
+    }
+  });
+  return out;
+}
+
+/** An `if:` condition with its owning job. */
+export interface IfCondition {
+  job: string;
+  expr: string;
+}
+
+/** Extract every `if:` condition (job-level and step-level) with its job. */
+export function extractIfConditions(yaml: string): IfCondition[] {
+  const out: IfCondition[] = [];
+  scanJobLines(yaml, (job, line) => {
+    const m = line.match(/^\s+(?:- )?if:\s*(.+)$/);
+    if (m) out.push({ job, expr: m[1].trim().replace(/^['"]|['"]$/g, "") });
+  });
+  return out;
+}
+
+/** Extract each job's `runs-on:` value(s) as a flat list of labels. */
+export function extractRunsOnByJob(yaml: string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  scanJobLines(yaml, (job, line, indent, lineNo, lines) => {
+    const m = line.match(/^\s+runs-on:\s*(.*)$/);
+    if (!m) return;
+    const value = m[1].trim();
+    const labels: string[] = [];
+    if (value === "") {
+      for (let j = lineNo + 1; j < lines.length; j++) {
+        const item = lines[j].match(/^\s+- (.+)$/);
+        if (!item) break;
+        labels.push(item[1].trim().replace(/^['"]|['"]$/g, ""));
+      }
+    } else if (value.startsWith("[")) {
+      for (const part of value.replace(/^\[|\]$/g, "").split(",")) {
+        const t = part.trim().replace(/^['"]|['"]$/g, "");
+        if (t) labels.push(t);
+      }
+    } else {
+      labels.push(value.replace(/^['"]|['"]$/g, ""));
+    }
+    out.set(job, labels);
+  });
+  return out;
+}
+
+/** Pull every `${{ ... }}` expression body out of a string. */
+export function extractExpressions(text: string): string[] {
+  const out: string[] = [];
+  const re = /\$\{\{(.+?)\}\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    out.push(m[1].trim());
+  }
+  return out;
+}
+
+/** Every line inside the `jobs:` block paired with its owning job name. */
+export function jobLines(yaml: string): Array<{ job: string; line: string }> {
+  const out: Array<{ job: string; line: string }> = [];
+  scanJobLines(yaml, (job, line) => out.push({ job, line }));
+  return out;
+}
+
+/** All lines inside the `jobs:` block grouped by owning job. */
+export function linesByJob(yaml: string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  scanJobLines(yaml, (job, line) => {
+    const arr = out.get(job) ?? [];
+    arr.push(line);
+    out.set(job, arr);
+  });
+  return out;
+}
+
+/** Set of jobs that declare an `environment:`. */
+export function extractJobEnvironments(yaml: string): Set<string> {
+  const set = new Set<string>();
+  scanJobLines(yaml, (job, line) => {
+    if (/^\s+environment:/.test(line)) set.add(job);
+  });
+  return set;
+}
+
+/** Set of jobs whose body references a `secrets.` context. */
+export function jobsReferencingSecrets(yaml: string): Set<string> {
+  const set = new Set<string>();
+  scanJobLines(yaml, (job, line) => {
+    if (/secrets\./.test(line)) set.add(job);
+  });
+  return set;
+}
+
+/** A permissions value as it appears in YAML: a string preset or a scope map. */
+export type PermissionsValue = string | Record<string, string>;
+
+/** The workflow-level `permissions:` value, if present. */
+export function extractWorkflowPermissions(yaml: string): PermissionsValue | undefined {
+  const doc = parseDoc(yaml);
+  const perms = doc?.permissions;
+  if (typeof perms === "string") return perms;
+  if (perms && typeof perms === "object" && !Array.isArray(perms)) return perms as Record<string, string>;
+  return undefined;
+}
+
+/** Per-job `permissions:` values, keyed by job name. Only jobs that declare one. */
+export function extractJobPermissions(yaml: string): Map<string, PermissionsValue> {
+  const out = new Map<string, PermissionsValue>();
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    const perms = jobObj.permissions;
+    if (typeof perms === "string") out.set(job, perms);
+    else if (perms && typeof perms === "object" && !Array.isArray(perms)) out.set(job, perms as Record<string, string>);
+  }
+  return out;
+}
+
+/**
+ * Classify a permissions value's write surface.
+ * `writeAll` is the `write-all` blanket preset; `scopes` lists the individual
+ * scopes granted `write` in map form.
+ */
+export function writeSurface(perms: PermissionsValue): { writeAll: boolean; scopes: string[] } {
+  if (typeof perms === "string") {
+    return { writeAll: perms === "write-all", scopes: [] };
+  }
+  const scopes: string[] = [];
+  for (const [scope, level] of Object.entries(perms)) {
+    if (level === "write") scopes.push(scope);
+  }
+  return { writeAll: false, scopes };
+}
+
+/** True if the permissions value grants any write access (blanket or scoped). */
+export function grantsWrite(perms: PermissionsValue): boolean {
+  const { writeAll, scopes } = writeSurface(perms);
+  return writeAll || scopes.length > 0;
+}
+
+/**
+ * Split an action `uses:` value into its `owner/repo` slug and git ref.
+ * Returns undefined for local (`./`, `../`) and `docker://` references, which
+ * are not GitHub action repository references.
+ */
+export function parseActionUses(uses: string): { owner: string; repo: string; slug: string; gitRef: string } | undefined {
+  if (uses.startsWith("./") || uses.startsWith("../") || uses.startsWith("docker://")) return undefined;
+  const at = uses.lastIndexOf("@");
+  const path = at === -1 ? uses : uses.slice(0, at);
+  const gitRef = at === -1 ? "" : uses.slice(at + 1);
+  const segments = path.split("/");
+  if (segments.length < 2 || !segments[0] || !segments[1]) return undefined;
+  return { owner: segments[0], repo: segments[1], slug: `${segments[0]}/${segments[1]}`, gitRef };
+}

package/src/lint/rules/data/flagged-actions.ts

@@ -0,0 +1,36 @@
+/**
+ * Vendored snapshot of action `owner/repo` slugs that are archived/abandoned or
+ * carry a disclosed security issue. Used by GHA032.
+ *
+ * Advisory only, and necessarily incomplete. Refresh source: GitHub Security
+ * Advisories (GHSA), CVE feeds, and upstream "archived" repo status. Accept
+ * staleness — regenerate periodically by editing this map. A missing entry only
+ * means a known-bad upstream goes unflagged; it never blocks a build.
+ *
+ * Keep entries factual and dated so the advice stays actionable.
+ */
+export interface FlaggedAction {
+  /** Why the upstream is flagged. */
+  reason: string;
+  /** What to do instead. */
+  remediation: string;
+}
+
+export const FLAGGED_ACTIONS: Readonly<Record<string, FlaggedAction>> = {
+  "tj-actions/changed-files": {
+    reason: "supply-chain compromise disclosed March 2025 (CVE-2025-30066) — tags were repointed to leak CI secrets",
+    remediation: "pin to a vetted commit SHA from before the compromise, or migrate to an audited alternative",
+  },
+  "actions/setup-ruby": {
+    reason: "archived and unmaintained",
+    remediation: "use ruby/setup-ruby",
+  },
+  "actions/create-release": {
+    reason: "archived and unmaintained",
+    remediation: "use softprops/action-gh-release or the gh CLI",
+  },
+  "actions/upload-release-asset": {
+    reason: "archived and unmaintained",
+    remediation: "use softprops/action-gh-release or the gh CLI",
+  },
+};

package/src/lint/rules/data/known-action-slugs.ts

@@ -0,0 +1,38 @@
+/**
+ * Vendored snapshot of widely-used GitHub Action `owner/repo` slugs.
+ *
+ * Used by the look-alike check (GHA031) as the reference set: a `uses:` slug
+ * that is a near-miss (edit distance 1–2) of one of these — but not an exact
+ * match — is likely a typo or an impersonation of the popular action.
+ *
+ * Advisory only. Refresh source: the GitHub Marketplace "most-used" actions and
+ * the actions/* org. Accept staleness — regenerate periodically by editing this
+ * list; a stale entry only weakens look-alike detection, it never blocks a build.
+ */
+export const KNOWN_ACTION_SLUGS: readonly string[] = [
+  "actions/checkout",
+  "actions/setup-node",
+  "actions/setup-python",
+  "actions/setup-go",
+  "actions/setup-java",
+  "actions/setup-dotnet",
+  "actions/cache",
+  "actions/upload-artifact",
+  "actions/download-artifact",
+  "actions/github-script",
+  "actions/stale",
+  "actions/labeler",
+  "actions/dependency-review-action",
+  "docker/build-push-action",
+  "docker/login-action",
+  "docker/setup-buildx-action",
+  "docker/setup-qemu-action",
+  "docker/metadata-action",
+  "aws-actions/configure-aws-credentials",
+  "azure/login",
+  "google-github-actions/auth",
+  "hashicorp/setup-terraform",
+  "codecov/codecov-action",
+  "softprops/action-gh-release",
+  "peter-evans/create-pull-request",
+];

package/src/lint/rules/data/preinstalled-tools.ts

@@ -0,0 +1,36 @@
+/**
+ * Vendored snapshot of tools already present on GitHub-hosted runner images,
+ * used by GHA056 to flag redundant runtime installs that add third-party
+ * surface for no benefit.
+ *
+ * Advisory. Refresh source: the runner-images repository's installed-software
+ * manifests. Conservative on purpose — only tools that are reliably present
+ * across the common ubuntu/macos/windows images are listed.
+ */
+export const PREINSTALLED_TOOLS: readonly string[] = [
+  "git",
+  "curl",
+  "wget",
+  "jq",
+  "make",
+  "gcc",
+  "g++",
+  "zip",
+  "unzip",
+  "tar",
+  "docker",
+  "docker-compose",
+  "python3",
+  "pip3",
+  "node",
+  "npm",
+  "yarn",
+  "go",
+  "gh",
+  "aws",
+  "az",
+  "gcloud",
+  "kubectl",
+  "helm",
+  "terraform",
+];

package/src/lint/rules/data/risky-features.ts

@@ -0,0 +1,39 @@
+/**
+ * Vendored snapshot of GitHub Actions features with a known security or
+ * safety footgun, matched against emitted workflow YAML by GHA054.
+ *
+ * Advisory and necessarily incomplete. Refresh source: GitHub changelog
+ * deprecations and security hardening guidance. Editing this list is the
+ * refresh mechanism; a stale entry only weakens detection, never blocks a build.
+ */
+export interface RiskyFeature {
+  /** Pattern matched against the emitted YAML. */
+  pattern: RegExp;
+  /** Short label for the footgun. */
+  label: string;
+  /** What to do instead. */
+  advice: string;
+}
+
+export const RISKY_FEATURES: readonly RiskyFeature[] = [
+  {
+    pattern: /::set-output\s/,
+    label: "deprecated ::set-output:: workflow command",
+    advice: "write to $GITHUB_OUTPUT instead",
+  },
+  {
+    pattern: /::save-state\s/,
+    label: "deprecated ::save-state:: workflow command",
+    advice: "write to $GITHUB_STATE instead",
+  },
+  {
+    pattern: /ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION/,
+    label: "opt-in to an end-of-life Node.js runtime",
+    advice: "upgrade the action to a supported Node runtime instead of forcing the unsupported one",
+  },
+  {
+    pattern: /::add-mask::\$\{\{/,
+    label: "masking a dynamic value after it may have already been logged",
+    advice: "mask secrets at their source; ::add-mask:: on an interpolated value can leak before the mask applies",
+  },
+];

package/src/lint/rules/data/trusted-action-owners.ts

@@ -0,0 +1,12 @@
+/**
+ * Allowlist of trusted action owners (GitHub orgs) whose `uses:` references are
+ * exempt from the SHA-pinning check (GHA029).
+ *
+ * Ships EMPTY by default: chant recommends pinning every external reference to a
+ * full commit SHA, including first-party ones. Populate this set to silence the
+ * pinning check for orgs you have decided to trust by tag (e.g. your own org).
+ *
+ * This is a vendored, code-level allowlist — `PostSynthContext` carries no
+ * per-check runtime config channel today. Refresh it by editing this file.
+ */
+export const TRUSTED_ACTION_OWNERS: ReadonlySet<string> = new Set<string>([]);

package/src/lint/rules/data/untrusted-contexts.ts

@@ -0,0 +1,44 @@
+/**
+ * Vendored snapshot of GitHub Actions expression contexts that are
+ * attacker-controllable — their values come from event payloads a fork or an
+ * outside contributor can set. Interpolating them into a shell (`run:`), into
+ * `GITHUB_ENV`/`GITHUB_PATH`, or into another execution sink turns data into
+ * code (script injection).
+ *
+ * Source: GitHub's "Security hardening for GitHub Actions — understanding the
+ * risk of script injections" plus the commonly-cited untrusted-context list.
+ * Advisory and necessarily incomplete; refresh by editing this list.
+ */
+export const UNTRUSTED_CONTEXTS: readonly string[] = [
+  "github.event.issue.title",
+  "github.event.issue.body",
+  "github.event.pull_request.title",
+  "github.event.pull_request.body",
+  "github.event.pull_request.head.ref",
+  "github.event.pull_request.head.label",
+  "github.event.pull_request.head.repo.default_branch",
+  "github.event.comment.body",
+  "github.event.review.body",
+  "github.event.review_comment.body",
+  "github.event.discussion.title",
+  "github.event.discussion.body",
+  "github.event.head_commit.message",
+  "github.event.head_commit.author.email",
+  "github.event.head_commit.author.name",
+  "github.event.commits", // .*.message / .*.author.* (array — matched by prefix)
+  "github.event.pages", // .*.page_name
+  "github.head_ref",
+];
+
+/**
+ * Return the first untrusted context referenced inside an expression body, or
+ * undefined. Matches by substring so array element accesses
+ * (`github.event.commits[0].message`) are caught via their prefix.
+ */
+export function matchUntrustedContext(exprBody: string): string | undefined {
+  const normalized = exprBody.replace(/\s+/g, "");
+  for (const ctx of UNTRUSTED_CONTEXTS) {
+    if (normalized.includes(ctx.replace(/\s+/g, ""))) return ctx;
+  }
+  return undefined;
+}

package/src/plugin.test.ts

@@ -24,15 +24,61 @@ describe("githubPlugin", () => {
 
   test("provides post-synth checks", () => {
     const checks = githubPlugin.postSynthChecks!();
-    expect(checks.length).toBe(15);
+    expect(checks.length).toBe(45);
 
     const checkIds = checks.map((c) => c.id);
     expect(checkIds).toContain("GHA006");
     expect(checkIds).toContain("GHA009");
     expect(checkIds).toContain("GHA011");
+    expect(checkIds).toContain("GHA013");
     expect(checkIds).toContain("GHA017");
     expect(checkIds).toContain("GHA018");
     expect(checkIds).toContain("GHA019");
+    expect(checkIds).toContain("GHA029");
+    expect(checkIds).toContain("GHA030");
+    expect(checkIds).toContain("GHA031");
+    expect(checkIds).toContain("GHA032");
+    expect(checkIds).toContain("GHA033");
+    expect(checkIds).toContain("GHA034");
+    expect(checkIds).toContain("GHA035");
+    expect(checkIds).toContain("GHA036");
+    expect(checkIds).toContain("GHA037");
+    expect(checkIds).toContain("GHA038");
+    expect(checkIds).toContain("GHA039");
+    expect(checkIds).toContain("GHA040");
+    expect(checkIds).toContain("GHA041");
+    expect(checkIds).toContain("GHA042");
+    expect(checkIds).toContain("GHA043");
+    expect(checkIds).toContain("GHA044");
+    expect(checkIds).toContain("GHA045");
+    expect(checkIds).toContain("GHA046");
+    expect(checkIds).toContain("GHA047");
+    expect(checkIds).toContain("GHA048");
+    expect(checkIds).toContain("GHA049");
+    expect(checkIds).toContain("GHA050");
+    expect(checkIds).toContain("GHA051");
+    expect(checkIds).toContain("GHA052");
+    expect(checkIds).toContain("GHA053");
+    expect(checkIds).toContain("GHA054");
+    expect(checkIds).toContain("GHA055");
+    expect(checkIds).toContain("GHA056");
+    expect(checkIds).toContain("GHA057");
+    expect(checkIds).toContain("GHA058");
+  });
+
+  test("lint IDs are unique across rules and post-synth checks", () => {
+    const ruleIds = githubPlugin.lintRules!().map((r) => r.id);
+    const checkIds = githubPlugin.postSynthChecks!().map((c) => c.id);
+    const allIds = [...ruleIds, ...checkIds];
+
+    const seen = new Set<string>();
+    const duplicates = new Set<string>();
+    for (const id of allIds) {
+      if (seen.has(id)) duplicates.add(id);
+      seen.add(id);
+    }
+
+    expect(Array.from(duplicates)).toEqual([]);
   });
 
   test("provides intrinsics", () => {

package/src/serializer.ts

@@ -233,6 +233,7 @@ export const githubSerializer: Serializer = {
     const workflows: Array<[string, Declarable]> = [];
     const jobs: Array<[string, Declarable]> = [];
     const triggers: Array<[string, Declarable]> = [];
+    const dependabot: Array<[string, Declarable]> = [];
     const others: Array<[string, Declarable]> = [];
 
     for (const [name, entity] of entities) {
@@ -245,21 +246,53 @@ export const githubSerializer: Serializer = {
         jobs.push([name, entity]);
       } else if (isTriggerType(entityType)) {
         triggers.push([name, entity]);
+      } else if (entityType === "GitHub::Dependabot::Config") {
+        dependabot.push([name, entity]);
       } else {
         others.push([name, entity]);
       }
     }
 
-    // If multiple workflows, produce multiple files
-    if (workflows.length > 1) {
-      return serializeMultiWorkflow(workflows, jobs, triggers, entities, entityNames);
+    const workflowOut =
+      workflows.length > 1
+        ? serializeMultiWorkflow(workflows, jobs, triggers, entities, entityNames)
+        : serializeSingleWorkflow(workflows, jobs, triggers, entities, entityNames);
+
+    // A DependabotConfig emits an additional `.github/dependabot.yml` file
+    // alongside (or instead of) any workflow output.
+    if (dependabot.length > 0) {
+      const [, dep] = dependabot[0];
+      const depProps = (dep as unknown as Record<string, unknown>).props as Record<string, unknown>;
+      const dependabotYaml = emitDependabotYaml(depProps);
+      if (typeof workflowOut === "string") {
+        return { primary: workflowOut, files: { "dependabot.yml": dependabotYaml } };
+      }
+      return { ...workflowOut, files: { ...(workflowOut.files ?? {}), "dependabot.yml": dependabotYaml } };
     }
 
-    // Single workflow (or implicit workflow from jobs)
-    return serializeSingleWorkflow(workflows, jobs, triggers, entities, entityNames);
+    return workflowOut;
   },
 };
 
+/** Deep camelCase → kebab-case key conversion for dependabot props. */
+function deepKebabKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(deepKebabKeys);
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[toKebabCase(k)] = deepKebabKeys(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Serialize a DependabotConfig's props into `.github/dependabot.yml`. */
+function emitDependabotYaml(props: Record<string, unknown>): string {
+  const doc = deepKebabKeys(props) as Record<string, unknown>;
+  return emitYAMLDocument(doc);
+}
+
 function serializeSingleWorkflow(
   workflows: Array<[string, Declarable]>,
   jobs: Array<[string, Declarable]>,