Dependabot Config

---
name: dependabot-config
description: "Reference for `.github/dependabot.yml` - GitHub-native dependency-update orchestrator. Required keys (`version: 2`, `updates[]` array) plus per-update fields (`package-ecosystem`, `directory` / `directories`, `schedule.interval`); common optional fields (`ignore`, `groups`, `allow`, `labels`, `milestone`, `open-pull-requests-limit`, `target-branch`, `vendor`, `versioning-strategy`, `assignees`, `commit-message`); auto-rebase + grouped-PR + security-only updates. Use when authoring or reviewing Dependabot configs in GitHub-hosted repos."
---

# dependabot-config

## Overview

[db-cfg]: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file

Per [db-cfg][db-cfg], Dependabot opens PRs (or issues, for security-only
updates) when a new version is available for a declared dependency, configured
via `.github/dependabot.yml` at the repo root.

This is a **reference skill** - it defines the config surface; it doesn't run
scans (that's `snyk-test` or `osv-scanner`). Dependabot complements SCA tools by
automating the upgrade PR.

## When to use

- The repo is GitHub-hosted (Dependabot is GitHub-native).
- Authoring a new `.github/dependabot.yml`.
- Reviewing a `.github/dependabot.yml` PR for completeness +
  hygiene.
- Migrating from manual update sweeps to automated orchestration.

For non-GitHub repos, see `renovate-config`.

## Step 1 - Top-level structure

Per [db-cfg][db-cfg]:

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
```

Required top-level keys:

| Key | Use |
|---|---|
| `version` | Always `2` (only supported version) |
| `updates` | Array of per-ecosystem update configurations |

## Step 2 - Per-update required fields

Per [db-cfg][db-cfg]:

| Field | Use |
|---|---|
| `package-ecosystem` | Package manager: `npm`, `bundler`, `cargo`, `composer`, `docker`, `github-actions`, `gitsubmodule`, `gomod`, `gradle`, `maven`, `mix`, `nuget`, `pip`, `pub`, `swift`, `terraform` |
| `directory` (or `directories`) | Manifest location relative to repo root |
| `schedule.interval` | Frequency: `daily` / `weekly` / `monthly` / `quarterly` / `semiannually` / `yearly` / `cron` (with cron expression) |

`directories` (plural) supports an array for monorepos:

```yaml
- package-ecosystem: "npm"
  directories:
    - "/services/api"
    - "/services/worker"
    - "/packages/shared"
```

## Step 3 - Common optional fields

Per [db-cfg][db-cfg]:

### `ignore`

> "Ignore updates for dependencies with matching names, optionally
> using `*` to match zero or" more characters.

```yaml
ignore:
  - dependency-name: "lodash"
    versions: [">=5.0.0"]    # don't update past v5
  - dependency-name: "*-internal-*"
    update-types: ["version-update:semver-major"]
```

### `groups`

> "Combines multiple dependency updates into single pull requests
> using pattern matching and dependency type filters."

```yaml
groups:
  dev-deps:
    dependency-type: "development"
    update-types: ["minor", "patch"]
  production-deps:
    dependency-type: "production"
    exclude-patterns: ["express*", "fastify*"]
```

Grouped PRs reduce review noise - instead of 30 individual PRs for
dev-deps, get one consolidated PR.

### `allow`

> "Restricts updates to explicitly listed dependencies only."

```yaml
allow:
  - dependency-name: "react*"
  - dependency-type: "direct"
```

Use carefully - overly-narrow `allow` lists silently drop coverage
of newly-added deps.

### Other common fields

| Field | Use |
|---|---|
| `labels` | Custom PR labels (overrides default `dependencies`) |
| `milestone` | Numeric milestone ID for created PRs |
| `open-pull-requests-limit` | Max concurrent version PRs (default 5; security-only PRs not counted) |
| `target-branch` | Update target branch (security PRs always go to default branch) |
| `vendor` | Maintain vendored deps (Bundler, Go modules) |
| `versioning-strategy` | `auto` / `strict` / `increase-if-necessary` / `widen-ranges` |
| `assignees` | GitHub usernames for assignment |
| `commit-message` | Customize prefix + scope |

## Step 4 - Realistic multi-ecosystem example

One `updates` entry per ecosystem, each with its own `schedule` and `labels`
(reuse the `groups` / `ignore` blocks from Step 3 as needed):

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
    open-pull-requests-limit: 10
    groups:
      dev-deps:
        dependency-type: "development"
    labels: ["dependencies", "javascript"]

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"

  - package-ecosystem: "docker"
    directory: "/Dockerfile"
    schedule:
      interval: "weekly"
```

Full config with per-ecosystem groups, ignore rules, assignees, and
commit-message customization:
[references/dependabot-advanced.md](references/dependabot-advanced.md).

**Verify:** after committing `.github/dependabot.yml`, open the repo's
Dependabot view (Insights -> Dependency graph -> Dependabot) and confirm GitHub
reports no `dependabot.yml` parse error and lists every configured
`package-ecosystem`; if it flags a parse error, fix the reported key and re-push
before relying on the config. Use the view's **Check for updates** control to
force a run instead of waiting for the `schedule`.

## Step 5 - Security updates (always-on)

Dependabot security updates are **enabled separately** in
repo settings (Security → Code security and analysis → Dependabot
security updates). Security PRs:

- Always target the default branch (regardless of `target-branch`)
- Don't count against `open-pull-requests-limit`
- Trigger immediately on CVE disclosure (not on schedule)
- Bypass `ignore` rules for the affected version (you can ignore
  the package generally, but Dependabot will still PR a security
  fix unless you explicitly ignore the CVE)

## Step 6 - False-positive triage analogue

Dependabot doesn't produce findings to triage - it produces upgrade
PRs. The "FP triage" analogue is **suppressing unwanted update PRs**:

| Mechanism | Use |
|---|---|
| `ignore.dependency-name` + `versions` range | Pin a dep to a major version (avoid breaking changes) |
| `ignore.update-types` | Block all major-version PRs for a dep |
| Repo Settings → Security → Disable Dependabot for a specific package | Categorical disable (last resort) |

**Justification template (mandatory in `dependabot.yml` comments):**

```yaml
ignore:
  # Reason: react v19 + react-router v7 incompatibility blocks upgrade
  # Approved-by: alice@example.com
  # Re-review-date: 2026-09-15 (re-evaluate when react-router v8 ships)
  - dependency-name: "react"
    update-types: ["version-update:semver-major"]
```

Cadence: every quarter, audit `ignore:` entries; expired re-review
dates removed.

## Step 7 - Auto-merge integration

Dependabot creates PRs but doesn't auto-merge. For auto-merge, pair with GitHub
Auto-merge or a workflow that reads `dependabot/fetch-metadata` and gates the
merge to `version-update:semver-patch` only (after CI passes; patch-only is
safer than minor / major). Full workflow:
[references/dependabot-advanced.md](references/dependabot-advanced.md).

## Anti-patterns

| Anti-pattern | Why it fails | Fix |
|---|---|---|
| `interval: "daily"` everywhere | PR storm overwhelms reviewers | `weekly` for non-critical; `daily` only for security-sensitive deps |
| No `groups:` for dev deps | Each dev-dep update is a separate PR | Group by dependency-type (Step 3) |
| `ignore` without expiration comment | Permanent debt | Mandatory `Re-review-date:` (Step 6) |
| Skip security-only updates feature (or disable in Settings) | Critical CVEs reach prod | Keep enabled; never disable wholesale |
| Auto-merge minor/major automatically | Breaking changes ship without review | Auto-merge patch only (Step 7) |

## Limitations

- GitHub-only - for GitLab / Bitbucket / non-GitHub, use
  `renovate-config`.
- No support for non-language manifests (Helm Chart.yaml,
  pre-commit hook updates, etc.) without workarounds.
- Grouped PRs introduce coupling - one breaking change blocks the
  whole group.
- Per-CVE waivers (vs per-version-range) are not first-class; the
  `ignore` mechanism is dependency-centric.

## References

- [db-cfg][db-cfg] - official configuration reference
- [references/dependabot-advanced.md](references/dependabot-advanced.md) - full
  multi-ecosystem config example + patch-only auto-merge workflow
- docs.github.com/en/code-security/dependabot - full Dependabot docs
- docs.github.com/en/code-security/dependabot/dependabot-security-updates - security updates feature
- github.com/dependabot/fetch-metadata - auto-merge helper
- `snyk-test`,
  `osv-scanner`,
  `renovate-config`,
  `npm-pip-maven-audit` - 
  sister tools