# dependabot.yml 設定完全ガイド：schedule・groups・cooldown・ignore・registries・モノレポを実コードで使いこなす > GitHub の dependabot.yml を本番品質で書くための設定完全ガイド。公式の設定リファレンス（2026年6月時点）に忠実に、package-ecosystem の全対応リスト、directory と directories（グロブ）、schedule と cooldown、groups（applies-to / group-by）、allow と ignore の優先順位、registries とプライベートレジストリ認証、commit-message、target-branch、multi-ecosystem-groups までを、コピペできる実例で解説します。 - 公開日: 2026-06-28 - 著者: 友田 陽大 - タグ: Dependabot, GitHub Actions, 依存関係管理, DevSecOps, サプライチェーンセキュリティ, 設定ファイル - URL: https://tomodahinata.com/blog/dependabot-yml-configuration-complete-guide - カテゴリ: Dependabot・依存関係の自動更新 - 総合ガイド: https://tomodahinata.com/blog/dependabot-production-guide ## 要点 - dependabot.yml は version: 2 と updates が必須。各 updates エントリは『package-ecosystem × directory(またはdirectories) × schedule.interval』が最小単位 - PR洪水は groups（まとめる）・cooldown（リリース直後を寝かせる）・open-pull-requests-limit（上限）で構造的に抑える。groups は applies-to: security-updates でセキュリティ更新にも効く - allow と ignore の両方にマッチした依存は『ignore が勝つ』。ignore は塩漬けの温床になりやすいので update-types を使った限定的な指定に留め、棚卸し対象にする - プライベートレジストリは top-level registries で定義し、認証情報は Dependabot シークレット（${{secrets.NAME}}）で渡す。リポジトリにハードコードしない - モノレポは directories のグロブ（例 /packages/*）で1エントリに集約し、group-by: dependency-name でディレクトリ横断のまとめPRにできる。multi-ecosystem-groups で複数エコシステムを1PRに束ねることも可能 --- `dependabot.yml` は「置けば動く」ファイルですが、**雑に置くとPRが洪水になり、丁寧に書くと依存管理が静かに自動化される**——その差がほぼ全部このファイルに詰まっています。この記事は[Dependabot 本番運用ガイド](/blog/dependabot-production-guide)の各論として、`dependabot.yml` の**全オプションを実コードで**解説します。手元に置いて引ける**リファレンス**として書きました。 > **この記事のルール**：キー名・既定値・対応エコシステムは **GitHub 公式の設定リファレンス（2026年6月時点）** に基づきます。Dependabot はオプション追加が速く、`cooldown`・`directories`（グロブ）・`multi-ecosystem-groups` などは比較的新しい機能です。本番前に必ず[公式リファレンス](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference)で最新を確認してください。 --- ## 0. ファイルの場所と全体構造 設置場所は**リポジトリ直下の `.github/dependabot.yml`**（YAML）。トップレベルのキーは4つだけです。 ```yaml 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 単一ディレクトリ ```yaml - package-ecosystem: "npm" directory: "/" # リポジトリ直下の package.json schedule: interval: "weekly" ``` ### 2.2 複数ディレクトリ・グロブ（モノレポの主役） `directories`（複数形）は**配列**で、しかも**グロブ（`*` / `**`）**が使えます。モノレポで `packages/a`, `packages/b`, ... を**1エントリに集約**できるのが強力です。 ```yaml - package-ecosystem: "npm" directories: - "/" - "/apps/*" # apps 配下の各アプリ - "/packages/**" # packages 配下を再帰的に schedule: interval: "weekly" ``` これがない時代は、ディレクトリの数だけ `updates` エントリを書いていました。グロブ1行で済むのは DRY そのものです。 --- ## 3. schedule：いつ動かすか ```yaml 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**に束ねます。 ```yaml - 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 セキュリティ更新もまとめる ```yaml groups: security-all: applies-to: security-updates # セキュリティ更新を1PRに束ねる patterns: ["*"] ``` ただし公式の制約として、**異なるエコシステムをまたいだグループ化はできず、セキュリティ更新とバージョン更新を同一PRに混ぜることもできません**。 ### 4.2 モノレポでディレクトリ横断にまとめる ```yaml - 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される版や出たての回帰を踏みにくくなります。 ```yaml 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：明示的に対象にする ```yaml allow: - dependency-type: "direct" # direct / indirect / all / production / development - dependency-name: "express" # update-types で粒度も指定可 ``` ### 6.2 ignore：対象から外す ```yaml 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 の見た目と取り回し ```yaml 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 シークレットで渡します**。 ```yaml 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 依存を一括で上げたい」ようなケースに使います。 ```yaml 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） ここまでを束ねた、**そのまま使える本番テンプレート**です。 ```yaml 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 自動化ガイド](/blog/dependabot-auto-merge-github-actions-automation-guide)へ。脆弱性対応の設定（grouped security updates / auto-triage）は[アラート・セキュリティ更新ガイド](/blog/dependabot-security-updates-alerts-vulnerability-management-guide)で扱います。 --- ## 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** タブで、各エコシステムの最終実行とログを確認できます。