Dependabot Setup

Skill: dependabot-setup

Analyzes .github/dependabot.yml — creating it if missing, repairing it if it deviates — and works collaboratively: gather evidence first, present findings and a recommended mode with reasons, let the user decide via AskUserQuestion, then write. Never overwrite an existing config without showing what's wrong with it. Pinned versions are the entry ticket: a Dependabot config over floating versions is theater, so the pin gate (Phase 3, delegating to the pin-node-dependencies / pin-github-actions siblings) must resolve before anything is written.

Run this when asked to "set up dependabot", review an existing config, or as the dependency-automation slice of a supply-chain audit (sibling skill release-audit).

The three modes

The core decision is how much review attention dependency PRs deserve. Ready-to-adapt templates ship in reference/ next to this SKILL.md.

"Cadence starting point" is the mode's default before per-ecosystem tuning — see Per-ecosystem cadence in Phase 1 and the confirmation step in Phase 4. Security updates are never affected by schedule.interval (Dependabot opens those the moment a vulnerability is detected regardless of cadence), so the interval only trades off routine-update noise vs. staleness.

Within low-noise, one PR per ecosystem is the default: a single-tech repo is simply one fully-grouped block, and unrelated stacks (npm frontend + gradle backend) stay in separate PRs so a broken gradle major never blocks frontend updates. The repo-wide single PR is the escalation for when even one PR per ecosystem is too many — never for unrelated stacks.

The mode may differ per ecosystem: even in balanced mode, github-actions is commonly fully grouped (majors are mostly mechanical when actions are SHA-pinned and CI gates); keep actions majors separate only when workflows are the release pipeline.

Stack-groups variants — width follows repo type. When Phase 1d finds coupling (dependencies across ecosystems tracking the same underlying software), two widths can bundle it, both orthogonal to the mode. The choice is driven by what the repo is (Phase 1b), not by how many dependencies happen to be coupled:

• Wide (mode-stack-groups.yml) — bundle each coupled ecosystem whole into one PR per stack (all gradle + all docker/compose as one backend group; backend & client in lockstep; terraform + infra images). Right for solution templates, examples, internal repos not consumed by other projects: nobody reviews these PRs individually, CI is the gate, and consolidation beats precision.
• Narrow (mode-fine-grained-stack-groups.yml) — only the coupled dependency pair joins a multi-ecosystem group; the rest of each ecosystem keeps normal per-ecosystem handling. Right for libraries/OSS consumed elsewhere, or a large dependency tree, where unrelated majors still deserve individual review. Two blocks per coupled ecosystem, same directory: a "regular" block with the ecosystem's normal groups that ignores the coupled dependency, and a "stack" block scoped via patterns to just that dependency, joining the shared multi-ecosystem-group — ignore only suppresses updates within the block that declares it, so the stack block still gets version and security updates for the coupled dependency.

Trade-offs to state for either width when proposing a stack group: the stack shares one CI gate; everything the patterns match rides together, majors included; and a member block that joins a multi-ecosystem group carries only package-ecosystem, directory, patterns, and multi-ecosystem-group — schedule/labels live on the group, and cooldown, commit-message, and groups cannot sit on members. So every ecosystem pulled into a stack loses its per-block cooldown, commit-message prefix, and forced applies-to: security-updates grouping. Keep an ecosystem whose majors (or those knobs) need individual handling out of the stack, in a normal balanced/fine-grained block (mixing is fine).

Phase 1 — Discover

a) Ecosystems. Find every manifest Dependabot can watch, including nested ones (each distinct directory needs its own directory, or one block with a directories glob list):

find . -path ./node_modules -prune -o \( -name package.json -o -name 'Dockerfile*' -o -name pom.xml \
  -o -name 'build.gradle*' -o -name go.mod -o -name Cargo.toml -o -name '*.tf' -o -name pyproject.toml \) -print
ls .github/workflows/ 2>/dev/null

Full ecosystem list: the options reference.

b) Repo identity — the primary evidence. The mode follows from what the repo is and who it serves — not from how updates were handled so far:

gh repo view --json isTemplate,isFork,isArchived,visibility,stargazerCount,description,licenseInfo
head -50 README.md                                       # what is this, who consumes it?
gh release list --limit 5 2>/dev/null                    # does it actually publish?
ls .github/workflows/                                    # is there a CI test job that gates PRs?
jq '(.dependencies//{}|length) + (.devDependencies//{}|length)' package.json 2>/dev/null   # dep count per ecosystem

Answer these explicitly before recommending anything:

• Purpose — product people depend on, library/package others consume, solution template, example/demo, internal tooling?
• Audience — open-source with external users, or closed/internal where the team is the only consumer?
• What it ships — how many artifacts does it deploy or publish (npm packages, container images, marketplace extensions)? Every published artifact raises the cost of a silently-broken major.
• Safety net — CI tests that actually gate merges; release automation.
• Scale & shape — dep count per ecosystem, number of packages/workspaces. (Cross-ecosystem coupling is its own mandatory step — see d below.)

Per-ecosystem cadence. The mode sets a starting point, but schedule.interval is decided per ecosystem, not once for the whole config — different ecosystems in the same repo release at different speeds:

Treat this table as a heuristic to seed the Phase 4 question, not a rule to apply silently — always confirm the actual interval per ecosystem with the user rather than defaulting to the mode's starting point.

c) Update history — calibration only, never the basis. The existing config and past habits may be exactly what needs to change; deriving the target from the status quo would just ratify it. Use history to tune within the recommended mode:

gh pr list --author 'app/dependabot' --state all --limit 100 --json state,createdAt,closedAt,mergedAt,title

• Many closed-without-merge / PRs open 30+ days → noise exceeded capacity → slower cadence or higher cooldown inside the chosen mode.
• Grouped PRs repeatedly superseded, conflicting, or red → groups too broad → corroborates fine-grained.
• Patches merge fast, majors rot → raise semver-major-days cooldown, don't change mode.

d) Cross-ecosystem coupling — mandatory, explicit. Coupling is not a judgement call to leave to prose — run it as an explicit step. After collecting the pinned version of every dependency in every ecosystem (you read these anyway for the Phase 3 pin gate), identify dependencies in different ecosystems that track the same underlying software or release train, and flag each such pair as a coupled candidate — manifests that must bump together. Two signals surface a pair, don't rely on only the first: an identical version string shared across manifests (the strongest and easiest to grep — e.g. one library pinned in two places), and different version strings that nonetheless track one product — a server and the client library that talks to it version their releases independently, so a literal-value match would miss them; recognise the shared software by name, not by number.

Stay general — flag any shared software, not just the familiar shapes. Illustrative pairs only:

• a server image in docker/docker-compose and its client SDK or driver in npm/gradle/pip — e.g. the postgres image (tag 16) and the org.postgresql:postgresql driver (42.7.x): different version numbers, same server, must move together
• a backend library and the client's pinned copy of the same library — usually an identical version string (backend & client released in lockstep)
• a provider/tool and the deployed image tag it manages — e.g. a terraform provider and the infra image it provisions (typically different numbers)

Every coupled pair becomes a candidate carried into Phase 4, where the width of the bundle is chosen by repo type. If nothing across ecosystems tracks the same software, record "no coupling found" and skip the stack-group variants.

Phase 2 — Analyze the existing config (if present)

Check each update block:

• Coverage — a block (or directories entry) for every ecosystem/directory from Phase 1; no orphan blocks for manifests that no longer exist.
• Mode coherence — which mode does the config resemble, and is it consistent across blocks? A "balanced" repo with one all-types group hides breaking majors inside routine PRs — finding.
• Dead & deprecated config:
  • reviewers: — removed by GitHub (Aug 2025), silently ignored → delete, wire CODEOWNERS instead.
  • target-branch: — a block with target-branch no longer applies to security updates, even when it names the default branch. Flag redundant target-branch: main for removal.
  • Duplicate blocks (same ecosystem + directory), overlapping directory/directories definitions.
• Reviewer wiring — for a repo owned by a small group, prefer one CODEOWNERS * rule over per-block assignees: it covers all PRs (not just Dependabot's) and doesn't rot in N places. Keep assignees only where a dedicated person triages dependency PRs separately from code ownership (larger orgs).
• Groups correct:
  • Group order matters — first match wins; specific families must precede the catch-all.
  • A group only affects version updates unless it says otherwise: without an applies-to: security-updates group, every CVE opens its own PR.
• Noise controls — cooldown present (supply-chain guard: new releases mature before a PR opens); open-pull-requests-limit sized to the expected PR count (default 5 — too low for balanced mode where majors arrive individually).
• Clutter — labels that don't exist in the repo or are typo'd (gh label list; e.g. "Technical Dept"), schedule.time without timezone (runs UTC), restated defaults, versioning-strategy that fights an exact-pin policy (widen vs pinned versions).
• Right-sizing & dead fields — the config must match the ecosystem's actual dependency shape (dep count, prod-vs-dev split), not a template's worst case. Flag:
  • update-types on a group that restates the default set — a version-updates group with no update-types already covers all of patch+minor+major, so update-types: ['patch','minor','major'] is a no-op; write update-types only when genuinely narrowing (e.g. ['minor','patch'] in balanced mode to hold majors out). (Security-updates groups take no update-types at all.)
  • A commit-message.prefix that can never fire for that ecosystem's dependency class. prefix-development applies only to updates in the development group and only for the ecosystems that have that concept (bundler, composer, mix, maven, npm, pip, uv); prefix covers everything else. So a prefix/prefix-development split in an ecosystem whose deps are all devDependencies leaves prefix dead (only prefix-development ever fires) — and all-prod leaves prefix-development dead. Collapse to a single prefix unless the ecosystem actually has both classes.
  • Group count out of proportion to dep count — a handful of named family groups over an ecosystem with only 2–3 direct deps is over-engineering; one grouped block (+ the security group) is enough. Reserve fine-grained family groups for genuinely large trees (see the mode table).

Phase 3 — Precondition: versions must be pinned

Dependabot PRs only reflect reality when manifests state exact versions — on floating specs the resolved dependency drifts on every install and the whole setup is theater. Treat pinning as a gate, not a finding: do not write a config while versions float.

Check per ecosystem, report with file:line evidence:

• npm — no ^/~/>=/*/latest/mutable git refs; lockfile committed → fix via sibling skill pin-node-dependencies
• github-actions — every uses: pinned to a full 40-char commit SHA → fix via sibling skill pin-github-actions
• docker / docker-compose — exact tag, ideally tag + @sha256: digest, never latest
• maven / gradle — no dynamic versions (1.+, [1.0,), latest.release)
• pip — == pins or a committed lockfile (uv / poetry / pip-tools)

If anything floats, resolve the gate before Phase 5 via AskUserQuestion: fix pins now (recommended — invoke the sibling skills for npm and actions, patch the other ecosystems directly) or proceed anyway, with the user explicitly accepting that Dependabot PRs for the floating ecosystems won't match what actually runs. Record the choice in the Phase 4 report.

Phase 4 — Report, recommend, decide

Post the findings as a normal message first — table of Phase 2/3 checks plus the mode recommendation. The recommendation derives from the repo's use-case (Phase 1b); update history (Phase 1c) only tunes cadence, cooldown, and group breadth within it. If the recommendation contradicts the current setup, say so and explain the delta — matching the status quo is not a goal:

Then confirm via AskUserQuestion — recommendation first, marked "(recommended)", every option stating its consequence. Ask only what the evidence can't answer, max 4 questions:

1. Mode — the three modes with one-line trade-offs. Include the single-PR multi-ecosystem variant only for clear low-noise repos. Whenever Phase 1d found coupling, surface both stack-group widths in the same question and mark the one matching the Phase-1b use-case "(recommended)":

   • wide — whole coupled ecosystems bundled (mode-stack-groups), recommended for solution-template/example/internal repos not consumed elsewhere (e.g. "all gradle + all docker/compose as one backend PR");
   • narrow — only the coupled pair joins the group, the rest stays per-ecosystem (mode-fine-grained-stack-groups), recommended for libraries/OSS consumed elsewhere or large dependency trees (e.g. "postgres image + postgres driver as one PR, rest of gradle/docker stays fine-grained").

   Name the concrete coupled manifests/pair. State the stack-group trade-off in the option text: bundled member blocks lose their per-block cooldown, commit-message prefix, and forced applies-to: security-updates grouping (schedule/labels live on the group; cooldown/commit-message/groups can't sit on members).

2. Cadence per ecosystem — always confirm, never silently apply the mode's starting point. Propose an interval per detected ecosystem from the Per-ecosystem cadence heuristic (Phase 1) adjusted by PR history (Phase 1c) and repo activity level, and let the user override any of them.

3. Review wiring — CODEOWNERS-only (recommended for small teams) vs keep assignees, only if the existing config has assignees/reviewers.

4. Existing customizations (multiSelect) — which ignore: rules, labels, or schedule quirks to carry over vs drop.

Phase 5 — Create or update

Enter this phase only once the Phase 3 pin gate is resolved — pins fixed (sibling skills run, other ecosystems patched) or floating versions explicitly accepted by the user.

• Update > replace. Fix the specific gaps; carry over confirmed customizations (especially ignore: rules) verbatim, including comments.

• Strip teaching comments — never emit them. The reference/mode-*.yml files carry long explanatory prose comments for agent context only; they must not appear in the generated .github/dependabot.yml. Copy the config shape, not the rationale. The written file keeps at most brief one-line section labels in the host repo's existing comment style (or none at all). This does not conflict with update > replace above: comments already present in the repo's own config (e.g. a rationale line on an ignore: rule) are still carried over verbatim.

• Start from the chosen reference/mode-*.yml, one block per detected ecosystem/directory. Templates show weekly/monthly as illustrative placeholders only — write the interval confirmed per ecosystem in Phase 4, not the template's literal value. For fine-grained: derive family groups from the actual manifests, never ship template families the repo doesn't use, and confirm the families with the user.

• Every mode keeps: labels: ['dependencies'], commit-message prefix chore + include: scope, cooldown, and an applies-to: security-updates group per ecosystem.

• Right-size to the ecosystem, don't emit dead fields (mirror the Phase 2 Right-sizing & dead fields check when writing, not just when auditing):

  • Omit update-types unless it genuinely narrows the set — a version-updates group without it already means all of patch+minor+major, so update-types: ['patch','minor','major'] is a no-op that reads as intent. In balanced mode the minor+patch group does carry update-types: ['minor','patch'] (that's the narrowing that keeps majors out); low-noise's all-in-one group carries none.
  • Emit a single commit-message.prefix unless the ecosystem actually mixes prod and dev deps. Don't add prefix-development for an ecosystem whose deps are all devDependencies (only it would fire, prefix is dead) or all prod (the reverse). prefix-development is meaningful only for bundler/composer/mix/maven/npm/pip/uv and only when both classes are present.
  • Scale groups to dep count: for a small ecosystem (a handful of direct deps) one grouped block plus the security group is the whole config — don't manufacture family groups the mode table reserves for large trees.
  • Grouped-PR prefix caveat: for a grouped update the PR title and branch come from the group's IDENTIFIER, not the commit-message prefix; the prefix still lands on the underlying commit, and prefix-development only applies when every member of that group is a dev dependency (a group mixing prod + dev deps falls back to prefix). So a dev-only ecosystem grouped into one PR consistently uses one prefix anyway — another reason not to split it.

• If no CODEOWNERS exists, create .github/CODEOWNERS with a default owner (suggest from gh api repos/{owner}/{repo} --jq .owner.login):

  # Default owners — requested as reviewers on every PR, including Dependabot's
  * @<owner-or-team>
  

• Ensure referenced labels exist: gh label create dependencies --description "Dependency updates" --color 0366d6 for any missing one.

Optional companion — patch/minor auto-merge

Auto-merge is owned by the sibling skill automerge-setup (the single source of truth for the workflow, its native-setting and required-check preconditions, and the scope gate). After the dependabot.yml is written, offer (never impose) to set up patch/minor auto-merge and hand off to automerge-setup — don't write .github/workflows/dependabot-automerge.yml from here. Auto-merge is only safe when a branch ruleset with a required status check gates the default branch (branch-ruleset-setup) and a CI test job runs on PRs (Phase 1b); automerge-setup enforces that precondition. Every major stays manual regardless.

Phase 6 — Verify

• YAML parses: python3 -c "import yaml; yaml.safe_load(open('.github/dependabot.yml'))" (fall back to npx --yes yaml or careful review).
• CODEOWNERS check after pushing: gh api repos/{owner}/{repo}/codeowners/errors.
• Config errors and run logs surface under Insights → Dependency graph → Dependabot — tell the user to check there after the merge, since GitHub validates unknown keys only at run time.
• If the user opted into auto-merge (Phase 5), the sibling automerge-setup handles and verifies the workflow; just confirm the hand-off happened.

Sources

• Options reference: https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference
• Grouped updates / PR optimization: https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/optimizing-pr-creation-version-updates
• Multi-ecosystem groups: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-multi-ecosystem-updates
• Targeted-pairing shape (two blocks, same ecosystem+directory, ignore + patterns/multi-ecosystem-group): https://github.com/dependabot/dependabot-core/discussions/12437
• Cross-directory group-by: dependency-name (Feb 2026): https://github.blog/changelog/2026-02-24-dependabot-can-group-updates-by-dependency-name-across-multiple-directories/
• reviewers removal in favor of CODEOWNERS: https://github.blog/changelog/2025-04-29-dependabot-reviewers-configuration-option-being-replaced-by-code-owners/
• Reference implementations: low-noise — https://github.com/Miragon/miravelo-shop-example/blob/main/.github/dependabot.yml · balanced — https://github.com/Miragon/bpmn-modeler/blob/main/.github/dependabot.yml