dependabot.yml は「置けば動く」ファイルですが、雑に置くとPRが洪水になり、丁寧に書くと依存管理が静かに自動化される——その差がほぼ全部このファイルに詰まっています。この記事はDependabot 本番運用ガイドの各論として、dependabot.yml の全オプションを実コードで解説します。手元に置いて引けるリファレンスとして書きました。
この記事のルール：キー名・既定値・対応エコシステムは GitHub 公式の設定リファレンス（2026年6月時点） に基づきます。Dependabot はオプション追加が速く、
cooldown・directories（グロブ）・multi-ecosystem-groupsなどは比較的新しい機能です。本番前に必ず公式リファレンスで最新を確認してください。
0. ファイルの場所と全体構造
設置場所はリポジトリ直下の .github/dependabot.yml（YAML）。トップレベルのキーは4つだけです。
version: 2 # 必須。現行スキーマは 2
updates: # 必須。エコシステムごとの更新設定（配列）
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
registries: # 任意。プライベートレジストリの認証情報
# ...
multi-ecosystem-groups: # 任意。複数エコシステムを1PRに束ねる（新機能）
# ...
updates 配列の各エントリが1つの更新ジョブです。最小単位は package-ecosystem（何を）× directory / directories（どこを）× schedule.interval（どの頻度で） の3つ。ここから肉付けしていきます。
1. package-ecosystem：対応エコシステム
package-ecosystem は更新対象のパッケージマネージャを指定します。2026年6月時点でサポートされるのは以下です（公式リスト）。
Bazel, Bundler, Bun, Cargo, Composer, Conda, Deno, Devcontainers, Docker, Docker Compose, Dotnet SDK, Elm, GitHub Actions, Gitsubmodule, Gomod, Gradle, Helm, Hex, Julia, Maven, Nix flakes, NPM and Yarn, NuGet, OpenTofu, Pip, pre-commit, Pub, Rust toolchain, sbt, Swift, Terraform, UV, vcpkg
設定ファイルに書く識別子は表記が決まっています。よく使うものを挙げます。
| エコシステム | package-ecosystem の値 | 対象になる主なファイル |
|---|---|---|
| npm / yarn / pnpm | npm | package.json, package-lock.json, yarn.lock, pnpm-lock.yaml |
| Python (pip/uv) | pip / uv | requirements.txt, pyproject.toml, uv.lock |
| Go modules | gomod | go.mod, go.sum |
| Docker | docker | Dockerfile |
| GitHub Actions | github-actions | .github/workflows/*.yml |
| Terraform | terraform | *.tf |
| Ruby | bundler | Gemfile, Gemfile.lock |
| Rust | cargo | Cargo.toml, Cargo.lock |
| Java | maven / gradle | pom.xml / build.gradle |
github-actionsは必ず入れる：ワークフローでuses:するアクションのバージョン（特に SHA 固定）も依存です。ここを更新対象にしないと、CI に紛れ込んだ古い・侵害されたアクションに気づけません。サプライチェーン防御の観点で最優先級です。
2. directory / directories：どこを見るか
2.1 単一ディレクトリ
- package-ecosystem: "npm"
directory: "/" # リポジトリ直下の package.json
schedule:
interval: "weekly"
2.2 複数ディレクトリ・グロブ（モノレポの主役）
directories（複数形）は配列で、しかもグロブ（* / **）が使えます。モノレポで packages/a, packages/b, ... を1エントリに集約できるのが強力です。
- package-ecosystem: "npm"
directories:
- "/"
- "/apps/*" # apps 配下の各アプリ
- "/packages/**" # packages 配下を再帰的に
schedule:
interval: "weekly"
これがない時代は、ディレクトリの数だけ updates エントリを書いていました。グロブ1行で済むのは DRY そのものです。
3. schedule：いつ動かすか
schedule:
interval: "weekly" # daily / weekly / monthly / quarterly / semiannually / yearly / cron
day: "monday" # interval が weekly のとき
time: "06:00" # HH:MM（24時間制）
timezone: "Asia/Tokyo" # IANA タイムゾーン
intervalはdaily/weekly/monthlyに加え、quarterly/semiannually/yearly/cronも指定できます（更新頻度の柔軟化）。time+timezoneで業務時間外に寄せると、朝イチでPRが並ぶのを避けられます。- セキュリティ更新はスケジュールに関わらず脆弱性検知時に動く点に注意（
scheduleはバージョン更新の頻度）。
実務のコツ：
dailyは活発なリポジトリでは多すぎることが多い。weekly+ 後述のgroups/cooldownから始め、滞留が出るなら頻度を上げるのが安全です。
4. groups：複数の更新を1つのPRにまとめる
PR洪水対策の本命。groups で関連する更新を1本のPRに束ねます。
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
groups:
# 型定義はまとめて
types:
patterns: ["@types/*"]
# テスト系をまとめて
testing:
patterns: ["jest", "vitest", "@testing-library/*", "playwright"]
# 上記以外の patch / minor をまとめる（major は個別PRのまま残す）
minor-and-patch:
update-types: ["minor", "patch"]
exclude-patterns: ["@types/*", "jest", "vitest"]
groups 配下の各グループで使えるキー：
| キー | 意味 |
|---|---|
patterns | グループに含める依存名のパターン（* ワイルドカード可） |
exclude-patterns | グループから除外するパターン |
applies-to | version-updates（既定）or security-updates。セキュリティ更新にもグループを効かせられる |
dependency-type | development or production |
update-types | patch / minor / major のどれを含めるか |
group-by | dependency-name。モノレポでディレクトリ横断に同じ依存をまとめる |
4.1 セキュリティ更新もまとめる
groups:
security-all:
applies-to: security-updates # セキュリティ更新を1PRに束ねる
patterns: ["*"]
ただし公式の制約として、異なるエコシステムをまたいだグループ化はできず、セキュリティ更新とバージョン更新を同一PRに混ぜることもできません。
4.2 モノレポでディレクトリ横断にまとめる
- package-ecosystem: "npm"
directories: ["/apps/*"]
schedule:
interval: "weekly"
groups:
react-across-apps:
patterns: ["react", "react-dom"]
group-by: "dependency-name" # 全 app の react 更新を1PRに
5. cooldown：リリース直後を寝かせる
cooldown（新しめのオプション）は、新バージョン公開から一定日数経つまでPRを開かない緩衝材です。公開直後にyankされる版や出たての回帰を踏みにくくなります。
cooldown:
default-days: 7 # 既定で7日待つ
semver-major-days: 30 # major は30日
semver-minor-days: 14 # minor は14日
semver-patch-days: 3 # patch は3日
include: ["next", "react"] # 対象を限定（最大150）
exclude: ["@types/*"] # 対象から除外（最大150）
- SemVer レベルごとに待機日数を変えられます（major ほど慎重に）。
cooldownはバージョン更新に適用され、セキュリティ更新（=急ぐ修正）には適用されません。これは合理的で、「鮮度維持は急がない、脆弱性修正は急ぐ」という運用思想と一致します。
6. allow / ignore：対象の絞り込みと除外
6.1 allow：明示的に対象にする
allow:
- dependency-type: "direct" # direct / indirect / all / production / development
- dependency-name: "express"
# update-types で粒度も指定可
6.2 ignore：対象から外す
ignore:
# この依存は完全に無視
- dependency-name: "aws-sdk"
# major だけ無視（patch/minorは追従する）— 実務で最も使う形
- dependency-name: "react"
update-types: ["version-update:semver-major"]
# 特定バージョン範囲を無視
- dependency-name: "lodash"
versions: [">= 5.0.0"]
優先順位（重要）：ある依存が
allowとignoreの両方にマッチした場合、ignoreが勝ちます（=無視される）。公式は「まず allow で対象を絞り、次に ignore で除外する。両方に該当したら ignore」と明記しています。
ignore の塩漬けに注意：「今は major を上げたくない」で
ignoreするのは妥当ですが、そのまま忘れると脆弱性が出たとき逃げ場がなくなります。update-types: ["version-update:semver-major"]のように範囲を限定し、四半期の棚卸しで見直す運用にしてください。ignoreは技術的負債の隠れ家になりがちです。
7. PR の見た目と取り回し
open-pull-requests-limit: 10 # 同時に開くPRの上限（バージョン更新の既定は5）
target-branch: "develop" # 既定ブランチ以外を対象にする
labels: ["dependencies", "automerge"] # PRに付けるラベル（既定を置き換える）
assignees: ["your-team-lead"] # アサイン先
milestone: 4 # マイルストーン番号
commit-message:
prefix: "chore(deps)" # 通常依存のコミット接頭辞（最大50文字）
prefix-development: "chore(deps-dev)" # 開発依存用
include: "scope" # スコープ（依存名）を件名に含める
pull-request-branch-name:
separator: "-" # Dependable のブランチ名の区切り文字
rebase-strategy: "auto" # auto / disabled / in-range
versioning-strategy: "increase" # エコシステム依存（lockfile-only 等も）
open-pull-requests-limit：バージョン更新の既定は 5。チームのレビュー処理能力に合わせる。セキュリティ更新は 10 固定（変更不可）。commit-message.prefix：Conventional Commits（chore(deps):）に揃えると、semantic-release等の自動化と相性が良い。labels：既定ラベルを置き換える点に注意（追加ではない）。automergeラベルで auto-merge ワークフローを駆動する設計も定番。reviewersは非推奨化しています。レビュアー指定はCODEOWNERSやブランチ保護の必須レビューに寄せるのが現行の推奨です。
8. registries：プライベートレジストリ認証
社内レジストリ（Artifactory, GitHub Packages, npm Enterprise, プライベート PyPI など）の依存も更新できます。認証情報は絶対にハードコードせず、Dependabot シークレットで渡します。
version: 2
registries:
npm-private:
type: npm-registry
url: https://npm.pkg.github.com
token: ${{secrets.DEPENDABOT_NPM_TOKEN}} # Dependabot シークレットを参照
python-artifactory:
type: python-index
url: https://artifactory.example.com/api/pypi/pypi/simple
username: ${{secrets.ARTIFACTORY_USER}}
password: ${{secrets.ARTIFACTORY_PASSWORD}}
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
registries:
- npm-private # この更新ジョブで使うレジストリを紐づける
ポイント：
${{secrets.NAME}}で参照するのは Dependabot 専用のシークレットストア（Settings → Secrets and variables → Dependabot）です。通常の Actions シークレットとは別物——侵害された依存が秘密情報を盗めないよう、Dependabot のワークフローは通常 Actions シークレットにアクセスできない設計だからです。- 外部から到達できないネットワーク内のレジストリは、self-hosted ランナーで Dependabot を走らせて到達します。
9. multi-ecosystem-groups：複数エコシステムを1PRに
multi-ecosystem-groups（新機能）は、異なるエコシステムの更新を横断して1つのPRにまとめる仕組みです。例えば「Docker のベースイメージと、その上で動く npm 依存を一括で上げたい」ようなケースに使います。
version: 2
multi-ecosystem-groups:
app-stack:
schedule:
interval: "weekly"
updates:
- package-ecosystem: "npm"
directory: "/"
multi-ecosystem-group: "app-stack" # このジョブをグループに所属させる
- package-ecosystem: "docker"
directory: "/"
multi-ecosystem-group: "app-stack"
通常の groups が1エコシステム内のまとめなのに対し、multi-ecosystem-groups はエコシステムをまたぐ点が違います。乱用するとPRが巨大化してレビュー困難になるため、関連が強い組み合わせに限定するのが KISS です。
10. 完成形：実戦的な dependabot.yml（Next.js × Docker × Actions）
ここまでを束ねた、そのまま使える本番テンプレートです。
version: 2
updates:
# ── アプリ依存（npm） ───────────────────────────
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
day: "monday"
time: "06:00"
timezone: "Asia/Tokyo"
open-pull-requests-limit: 10
commit-message:
prefix: "chore(deps)"
prefix-development: "chore(deps-dev)"
include: "scope"
cooldown:
default-days: 7
semver-major-days: 30
groups:
types:
patterns: ["@types/*"]
minor-and-patch:
update-types: ["minor", "patch"]
exclude-patterns: ["@types/*"]
ignore:
# major は人間が棚卸しで判断（patch/minor は自動追従）
- dependency-name: "*"
update-types: ["version-update:semver-major"]
labels: ["dependencies"]
# ── Docker ベースイメージ ───────────────────────
- package-ecosystem: "docker"
directory: "/"
schedule:
interval: "weekly"
commit-message:
prefix: "chore(docker)"
# ── GitHub Actions（サプライチェーン防御の要） ──
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
commit-message:
prefix: "ci"
この構成の意図：
- patch/minor は groups でまとめて自動追従、major は
ignoreで止めて人間が棚卸し——レビュー負荷を「中身のある変更」に集中させる。 - cooldown で出たての回帰を回避。
- Docker と GitHub Actions も対象に入れ、ベースイメージと CI のサプライチェーンを同時に守る。
- コミット接頭辞を Conventional Commits に揃え、リリース自動化と整合させる。
この ignore で止めた major と groups で流す patch/minor をどう自動マージするかは、auto-merge × GitHub Actions 自動化ガイドへ。脆弱性対応の設定（grouped security updates / auto-triage）はアラート・セキュリティ更新ガイドで扱います。
11. FAQ
Q. directory と directories はどう使い分けますか？
A. 単一なら directory: "/"、複数やモノレポなら directories: ["/apps/*", "/packages/**"]（グロブ可）。後者でエントリの重複を避けられます。
Q. major だけ自動更新を止めたい。
A. ignore に update-types: ["version-update:semver-major"] を指定します。patch/minor は追従しつつ major だけ止まります。塩漬け防止に棚卸し対象にしてください。
Q. allow と ignore が衝突したら？ A. ignore が優先されます（無視される）。
Q. プライベートレジストリのトークンはどこに置きますか？
A. Dependabot シークレット（Settings → Secrets and variables → Dependabot）に置き、${{secrets.NAME}} で参照します。Actions シークレットとは別ストアです。
Q. 設定が効いているか確認したい。 A. リポジトリの Insights → Dependency graph → Dependabot タブで、各エコシステムの最終実行とログを確認できます。