Dependabot まとめ

記事の内容

公式チュートリアルやりつつ、公式ドキュメント読みつつ、以下について詳しめにまとめた記事。

• 導入手順
• 使い方

さらなる詳細が知りたい場合は、公式ドキュメントを参照。
それぞれの具体的な手順およびそのスクショは、 2024/12 時点のものなので、経年で多少変化する可能性あり。

Dependabot とは

GitHub の1機能であり、GitHub リポジトリで使われている依存パッケージの管理について、以下の3機能を提供するもの。

• Dependabot alerts: 脆弱性のアラートを上げる
• Dependabot security updates: Dependabot alerts で挙げられた脆弱性へ対処する Pull Request (以降 PR) を自動で起票
• Dependabot version updates: 最新の状態に保つ PR を自動で起票

公式ドキュメントの各ページを確認した感じ、以下のような関係性になっている模様。

各パッケージの依存関係を管理する機能 Dependency graph を起点として、以下2つの処理の流れがある形。

• Dependency graph → Dependabot alerts → Dependabot security updates
• Dependency graph → Dependabot version updates

「alerts, security updates」 と 「version updates」 は互いに関係していない。

以降、3つ機能それぞれについて導入手順と使い方を説明する。

Dependabot alerts

導入

GitHub の Web コンソールで、導入対象のリポジトリに対して有効化する。
特定の条件を満たすものについて、アラートを上げないようにしたい場合は、 Dependabot auto-triage rule で設定する。

有効化の手順

GitHub へログイン > Dependabot を導入するリポジトリの Settings > Code security > Dependabot alerts の Enable ボタンを押下

アラートのフィルタリング設定手順

Dependabot alerts を有効化した状態で、Dependabot auto-triage でフィルタリングのルールを設定することができる。
GitHub 側で用意されている GitHub presets というルールが使えるほか、Custom auto-triage rules から独自のルールを設定できる。

それぞれ、対象リポジトリの
　Settings > Code security > Dependabot - Dependabot alerts - Dependabot rules
から設定できる。

GitHub presets

GitHub 側で用意されているルールで npm パッケージについてかなりの誤検出を抑えられる(らしい)。
パブリックリポジトリでは Dependabot alerts を有効化した段階で、デフォルトで有効化される(無効化も可能)。

Custom auto-triage rules

独自に指定した条件を満たすものについてアラートを上げないようにする他、「Dependabot security updates による PR 自動作成」を設定できるルール。

対象リポジトリの
　Settings > Code security > Dependabot - Dependabot alerts - Dependabot rules > New rule
からルールを作成できる。

設定項目は以下の通り

項目	説明
Rule name	ルール名
State	このルールを有効化する / 無効化する
Target alerts	条件の指定。「深刻度 /パッケージ名 / エコシステム名 / スコープ / マニフェスト名 / CWE 番号 / CVE の ID / GHSA の ID」 の & 条件で指定できる
Rules - Dissmiss alerts	アラートを上げないようにする。「脆弱性に対処するパッチが利用可能になるまで / 無期限に」を併せて設定する。
Rules - Open a pull request to resolve alerts	Dependabot alerts によって上げられたアラートについて、Dependabot security updates で脆弱性へ対処する PR を自動で起票する。リポジトリに対して　Dependabot security updates が有効化(後述)されていない場合のみ、条件指定で個別に設定可能という形。

使い方

Dependabot alerts を有効化したリポジトリで、

Security > Security overview - View Dependabot alerts

上げられているアラートを一覧で確認できる。

アラートを開くと、脆弱性があるパッケージ、対象バージョン、対処されるバージョン、脆弱性の内容 などを確認できる。

また、Dismiss alert ボタンから理由を選択しつつ無視することもできる。

• 修正をすでに開始している
• 修正するための余力がない
• リスクを許容する
• 誤報 or 不正確
• 脆弱性のあるコードが実際には適用されない

Dependabot security updates

有効化の手順

Dependabot alerts を有効化したリポジトリで、以下どちらかで Dependabot security updates を有効化できる。

• Dependabot alerts によって上げられるアラート全てについて一律に PR を自動で起票する
• Dependabot alerts によって上げられる特定のアラートのみ PR を自動で起票する

アラート全てについて PR を自動起票する場合

Settings > Code security > Dependabot - Dependabot security updates の Enable ボタンを押下

で有効化できる。

特定のアラートのみ PR を自動起票する場合

先述の Custom auto-triage rules で設定できる。

オプション設定

パッケージエコシステムごとに1 PR にまとめて起票させる場合

Dependabot security updates が有効化されている状態で、
Settings > Code security > Dependabot - Grouped security updates の Enable ボタン

から有効化できる。

詳細設定

後述の dependabot.yml という設定ファイルの記述により設定できる。

使い方

Dependabot security updates によって自動起票された PR で、以下の操作ができる。

• アップデートされるパッケージに含まれるコミットの確認
• Dependabot に対して以下の操作を依頼
  • PR ブランチの rebase
  • PR の再作成
  • CI 通過後に merge
  • CI 通過後に PR ブランチのコミットを squash & merge
  • PR の merge 依頼をキャンセル
  • PR の再オープン
  • PR のクローズ
  • 指定した依存パッケージの無視条件を一覧表示
• マージ: このとき関連する Dependabot alerts で上げられているアラートもクローズされる。

Dependabot version updates

有効化の手順

指定パッケージのバージョンを最新に保ちたいリポジトリに対して有効化することに加え、最新化したい対象を dependabot.yml という設定ファイルで指定する必要がある。

リポジトリに対する有効化

Settings > Code security > Dependabot - Dependabot version updates の Enable ボタン
から有効化できる。

最新化対象の指定

<リポジトリルート>/.github/dependabot.yml を作成してデフォルトブランチに含める。
dependabot.yml の中身については後述。

dependabot.yml

Dependabot security updates, Dependabot version updates の挙動をデフォルトから変更できる設定ファイル。YAML 形式のキーバリューで各項目を設定していく。

以下、各キーについて説明する。
設定が必須のキーは、名前の先頭に*を付けてある。
すべてのキーは version updates に対して作用するが、security updates に対しては作用しないキーがある。security updates に作用するキーについては明示する。

*version

version: 2 固定で記述。

*updates

依存関係のバージョン更新を設定するキー。

*updates[*].package-ecosystem

Dependabot に監視させたいパッケージマネージャに対して設定するキー。
リポジトリにはそのパッケージマネージャの依存関係のマニフェスト or ロックファイルが含まれていなければならない。

設定可能な値は、Configuration options for the dependabot.yml file - package-ecosystem に記載されている。

以下、値の例。

devcontainers
devcontainers の設定ファイル devcontainer.json の Features を更新する。
サポートの詳細と設定ファイルについては、General Availability of Dependabot Integration を参照。
関連する devcontainer.json の Features を最新のメジャーバージョンに固定する。
開発コンテナにロックファイルがある場合は、それも更新される。

github-actions
GitHub Actions のワークフロー設定ファイル .github/workflows/xxx.yml について、その設定で使われている Action を更新する。
actions/checkout@v4 のような GitHub リポジトリの構文のみが対象となり、ローカルの Action や再利用可能なワークフローは無視する（.github/actions/foo.yml など）
Docker Hub と GitHub パッケージ コンテナレジストリ URL はサポートされていない。
パブリックリポジトリとプライベートリポジトリ双方の Action をサポートする。
プライベートレジストリの設定オプションについては、git を参照。

gomod
Go モジュールの依存関係を管理するファイル go.mod を更新する。

npm
npm パッケージの依存関係を管理するファイル package.json を更新する。

terraform
以下がサポートされている

• Terraform レジストリにあるモジュール
• パブリックな Git リポジトリにあるモジュール
• Terraform プロバイダ
• プライベートな Terraformレジストリ。registries で git を指定することで、プライベートな git リポジトリへのアクセスも可能

*updates[*].directory

Dependabot security updates でも使われる。
directory か directories のどちらか一方が必須。

*updates[*].package-ecosystem で指定しているパッケージマネージャーのパッケージマニフェスト(package.json や Gemfile)の場所を設定するキー。
GitHub Actions を除くすべてのパッケージマネージャーについて、リポジトリルートからの相対パスで設定する(GitHub Actions では /.github/workflows と設定する必要はなく、/ と設定する)。

directory キーの代わりに directories キーを使用すると、複数のディレクトリに同じ設定を適用できる。
directory キーや directories キーは、同じ *updates[*].package-ecosystem と target-branch の値を持つブロックについて重複不可能。

dependabot.yml

version: 2
updates: 
  - package-ecosystem: "bundler"
    directory
    - "/"
    schedule:
      interval: "weekly"

*updates[*].directories

Dependabot security updates でも使われる。
directory か directories のどちらか一方が必須。
基本的な説明は *updates[*].directory の項を参照。

1つの *updates[*].package-ecosystem に対して、directory, directories を混在させることもできる。
設定するパスに、ワイルドカード * や ** を含めることができる。

dependabot.yml

version: 2
updates: 
  - package-ecosystem: "bundler"
    directories:
    - "*"  # ルートディレクトリおよびその直下のディレクトリ群
    - "**/*" # ルートディレクトリから再帰的に辿れるディレクトリ群
    schedule:
      interval: "weekly"
  - package-ecosystem: "bundler"
    directory:
    - "/dir-*" # `dir` で始まるルートディレクトリ直下のディレクトリ
    schedule:
      interval: "daily"

*updates[*].schedule.interval

ecosystem で指定しているパッケージマネージャーの新しいバージョンをチェックする頻度を設定するキー。
以下3つのどれかで指定できる。

• daily: 月〜金で毎日。
• weekly: 毎週。デフォルトは月曜だが、schedule.day で変更できる。
• monthly 毎月1日。
  デフォルトでは、Dependabot はすべてのパッケージの更新を適用する時間をランダムに決定する。
  特定の時間を設定したい場合は、さらにschedule.time と schedule.timezone キーで指定することができる。

registries

プライベートなパッケージレジストリへのアクセスするための認証情報を指定したい場合に設定するキー。
トップレベルに記述。

updates[*].allow

Dependabot security updates でも使われる。

デフォルトでは、マニフェストで明示的に定義されたすべての依存関係は、Dependabot version updates によって最新の状態に保たれる。
さらに、Dependabot security updates は、ロックファイルで定義されている脆弱な依存関係も更新する。
allow と ignore (後述) を使って、維持する依存関係をカスタマイズすることができる。
Dependabot は許可された依存関係をチェックし、無視された依存関係やバージョンを除外する。
allow と ignore の両方にマッチする依存関係は無視される。

dependency-name
これで指定した名前が一致する依存関係の更新を許可する。
ゼロ以上の任意の文字列として * を使うことができる。

dependency-type
特定のタイプの依存関係のみ更新を許可する場合に使用する。

• direct: 明示的に定義された全ての依存関係
• indirect: direct の依存関係の依存関係
• all: 全て
• production: production 向けの依存関係の設定のみ
• development: development 向けの依存関係の設定のみ

updates[*].assignees

Dependabot security updates でも使われる。

version updates, security updates で起票される PR について、 assignee (PR のマージ担当者)を指定する。

updates[*].commit-message

Dependabot security updates でも使われる。

Dependabot は、デフォルトでリポジトリの履歴からコミットメッセージの好みを検出して、類似パターンのコミットメッセージを付与しようとする。なお、Dependabot はこのキーで明示的に指定されたものであれ、デフォルト設定であれコミットメッセージに基づいて PR のタイトルを付与しようとするため、タイトルにも影響する。

updates[*].commit-message.prefix

Dependabot security updates でも使われる。

パッケージの依存関係を更新する PR のコミットメッセージにつけられるプレフィックスの文字列。
末尾が文字、数字、)、]の場合は、<prefix>: <本文>という形になり、空白の場合は<prefix><本文>という形になる。
例えば "xxx" とすると、本文の前に "xxx: <本文>" となり、"[xxx]" とすると、 "[xxx]本文" となる。
指定に50文字制限あり。

updates[*].commit-message.prefix-development

development 向けに必要なパッケージの依存関係(npm だと devDependencies で指定されるパッケージ)を更新する PR のコミットメッセージにつけられるプレフィックスの文字列。指定しない場合は、development 向けにも prefix の設定が適用される。
指定に50文字制限あり。

updates[*].commit-message.include

scope のみ設定可能。これを設定すると、producton 向けに必要なパッケージの依存関係ではプレフィックスに deps が、development 向けに必要なパッケージの依存関係では deps-dev が付与される。

所感:
deps は dependencies の略だと思われる。
production と development でコメントをわかりやすくわける場合には、include: scope か prefix-development のどちらかで十分。特に理由がなければinclude: scope にしておくのがよさそう。

updates[*].enable-beta-ecosystems

デフォルトでは、Dependabot は完全にサポートされているエコシステムのみチェックする。このキーを使用するとパブリックプレビュー中のエコシステムもチェックするようになる。
(が、現在パブリックプレビュー中のエコシステム該当はない)

updates[*].groups

Dependabot security updates でも使われる。

Dependabot update versions と Dependabot security updates によって作成される PR のグループ化ルールを作成できる。
Dependabot update versions のためのグループ化された PR に脆弱なパッケージが含まれている場合、Dependabot security updates は、脆弱なパッケージを安全なバージョンに更新するための別の PR を作成しようとする。

デフォルトでは、Dependabot は新しいバージョンに更新する必要がある依存関係ごとに単一の PR を起票する。
*updates[*].package-ecosystem で指定しているパッケージマネージャごとに依存関係のグループを作成し、Dependabot が複数の依存関係を同時に更新するために単一の PR をオープンするようにできる。
(まとめることで、後述の最大 PR 数の制限にも寄与することになる)

また、更新が特定のエコシステムにどのように影響するかに基づいてグループ化の設定を指定し、セマンティックバージョニング（SemVer）に従うこともできる。
例えば、すべてのパッチアップデートをまとめてグループ化することができる。
このアプローチは、Dependabotができるだけ少ないプルリクエストを作成するのを助けると同時に、問題を引き起こす可能性のある変更を誤って受け入れる可能性を減らす。
パッケージがSemVerに従っている場合、マイナーアップデートやパッチアップデートが後方互換性を持つ可能性が高くなる(保証はない)。

グループを設定する際にはまず、グループ名(PR のタイトルやブランチ名に表示される)とグループルールを Dependabot version updates に適用するか security updates に適用するかを指定する。
次に、特定の依存関係をグループに含めたり除外したりするためのオプションを定義する。
グループを定義するには、patterns、exclude-patterns、dependency-type、update-types オプションのいずれか、またはそれらの組み合わせを使用する必要がある。

どのグループにも属さない依存関係については、単一の P
R が起票される。

スケジュールされたアップデートが実行されると、Dependabot は以下のルールでグループ化されたアップデートのプルリクエストを更新する:

• すべての同じ依存関係を同じバージョンに更新する必要がある場合、Dependabot はブランチを rebase する
• 同じ依存関係をすべて更新する必要があるが、依存関係の1つ（または複数）に新しいバージョンが利用可能になった場合、Dependabot は既存の PR をクローズして新しく作成する。
• 更新する依存関係が変更された場合 - たとえば、グループ内の別の依存関係に更新が利用可能になった場合 - Dependabot は既存の PR をクローズして新しく作成する。

groups.<グループ名>.applies to
Dependabot version updates か Dependabot security updates どちらにグループのルールを適用するかを設定する。
要素として指定できる値は、以下の通り。

• version-updates
• security-updates

デフォルトは version-updates。
version-updates, security-updates 双方に同じ内容のグループルールを設定したい場合は、同じ package-ecosystem の updates の要素レベルから2つ必要になる。そのうえで、グループ名は別にしてやる必要がある。

groups.<group 名>.dependency-type
以下どちらかを指定する。

• development
• production

groups.<group 名>.patterns
依存関係名 (または複数の依存関係名) と一致する文字列を定義して、それらの依存関係をグループに含めるために使用する。

groups.<group 名>.exclude-patterns
特定の依存関係をグループから除外するために使用する。
依存関係がグループから除外されている場合、Dependabot はその依存関係を最新バージョンに更新するために単一の PR を起票し続ける。

groups.<group 名>.update-types
グループに含めるセマンティック・バージョニング・レベルを指定する。
指定できる値は以下の通り。

• `major
• `minor
• patch

updates[*].ignore

Dependabot security updates でも使われる。

デフォルトでは、マニフェストで定義されたすべての依存関係が、Dependabot version updates によって最新に保たれる。
さらに、Dependabot security updates は、ロックファイルで定義されている脆弱な依存関係も更新する。
allow と ignore を使って、維持する依存関係をカスタマイズできる。
Dependabot は allow で指定された依存関係をチェックし、その中で ignore で指定された依存関係やバージョンを除外する。

PR で @dependabot ignore で無視対象にした依存関係は、その無視情報がパッケージマネージャごとに保存・管理され、dependabot.yml の ignore 設定と併用される形になる。
PR 側で設定した無視情報は、@dependabot ignore で確認できる。

以下のキーを含む map で設定できる
dependency-name
ignore を使う場合必須。
このキーで指定したパターンに一致する依存関係の更新を無視する。
* は、0 個以上の文字列として使うことができる。

versions
指定したバージョン (の範囲) に限って更新を無視する。
デフォルトは全てのバージョンが対象。
バージョンは配列で指定する。
バージョンの指定には、ecosystem で指定しているパッケージマネージャでの標準的なパターンが使える。

update-types
セマンティックバージョンにおける、以下のアップデートを無視するために使うキー。
デフォルトは全て。

• version-update:semver-major: メジャーバージョンのアップデート
• version-update:semver-minor: マイナーバージョンのアップデート
• version-update_semver-patch: パッチバージョンのアップデート
  配列で指定する。

updates[*].insecure-external-code-execution

Dependabot security updates でも使われる。

updates[*].package-ecosystem で指定している値が
bundler, mix, pip に該当するパッケージマネージャでは、 バージョンアップデート処理の一部にマニフェスト内で外部コードを実行する可能性があり、これにより認証情報が盗まれたり、レジストリにアクセスされたりする可能性がある。registries の設定を追加すると、Dependabot は自動的に外部コードの実行を防ぐ。このキーに allow を設定することで、外部コードの実行を許可することができる。

updates[*].labels

Dependabot security updates でも使われる。

version updates, security updates で起票される PR に付与するラベルを指定する。デフォルトでは dependencies というラベルが付与される。ラベルの付与自体を無効化したい場合は、[]を指定する。

updates[*].milestone

Dependabot security updates でも使われる。

version updates, security updates で起票される PR について、 milestone を指定する。ただし、milestone は文字列ではなく、その ID で指定しなければならない。milestone の IDは、対象リポジトリの > Pull requests タブ > Milestones タブ > 対象 milestone

で開かれるページの URL 末尾の数値(https://github.com/<owner>/<repo>/milestone/1なら 1)。

updates[*].open-pull-requests-limit

Dependabot version updates がオープンする PR の最大数を設定するキー。
最大数に達すると、PR がマージされるかクローズされるまで新規にオープンされなくなる。
デフォルトの最大数は 5。

なお、Dependabot security updates がオープンする PR の最大数にはこの値が適用されない。
こちらは 10 固定である。

updates[*].pull-request-branch-name.separator

Dependabot security updates でも使われる。

version updates, security updates で起票される PR に伴って作成される作業ブランチ名に含まれるセパレータを設定する。デフォルトは /。設定できる値は "-", _, /のいずれか。

updates[*].rebase-strategy

Dependabot security updates でも使われる。

Dependabot はデフォルトで、version updates, security updates で起票される PR について変更を検出するとその PR を自動で rebase する(ただし、30日間マージされていない場合は自動 rebase をしなくなる)。

以下のどちらかを設定可能。

• auto: デフォルトの挙動。
• disabled: 自動 rebase を無効化

updates[*].registries

Dependabot security updates でも使われる。

Dependabot がプライベートパッケージレジストリにアクセスするための認証情報を指定する。
設定の詳細については、以下を参照。

updates[*].reviewers

Dependabot security updates でも使われる。

version updates, security updates で起票される PR について、 reviewer を指定する。

updates[*].schedule.day

updates[*].schedule.interval で　weekly を設定した場合に更新する曜日を指定できる。
指定しない場合、月曜になる。
sunday, monday, tuesday, wednesday, thursday, friday, saturday

updates[*].schedule.time

mm:dd で、更新時刻を指定できる。

updates[*].schedule.timezone

updates[*].schedule.time のタイムゾーンを指定できる。
指定できるのは、TZ identifier の値。

例 Asia/Tokyo

updates[*].target-branch

Dependabot はデフォルトで version updates による PR 作成のためにデフォルトブランチのマニフェストファイルをチェックする。このキーで別のブランチのマニフェストファイルをチェックさせることができる。ただし、このキーが含まれる updates[*] ブロック全体が security updates で使われなくなってしまうことに注意。なお、。security updates は、デフォルトブランチのマニフェストファイルしかチェックしない。

updates[*].vendor

Dependabot security updates でも使われる。

詳細は以下を参照。

updates[*].versioning-strategy

Dependabot security updates でも使われる。

詳細は以下を参照。

Dependabot による操作をトリガーに GitHub Actions で自動化

Dependabot による操作であるかの判断

workflow をトリガーしたのが Dependabot である場合、github.actor == 'dependabot[bot]' になる。

Dependabot が作成した PR に関する情報を取得

dependabot が作成した Action dependabot/fetch-metadataで、Dependabot が作成した PRについて諸々の情報が取得できる。
取得できる情報としては、PR 自体に載っている情報だけでなく、PR の作成に至るまでの Dependabot 内部処理に関するものもある。
多くの場合、input はデフォルトのままで使えそう。

verified な Action である。

以下、
dependabot/fetch-metadata の action.yml に載っている input, output の description を訳したもの。

---

input

alert-lookup
true の場合、output alert-state, ghsa-id, cvss を出力。

compat-lookup
true の場合、output compatibility-score を出力。

github-token
シークレット GITHUB_TOKEN。
デフォルト値は、コンテキスト github.token

skip-commit-verification
true の場合、Dependabot のコミットが検証されることを期待しない。これは GHES 環境でtrueに設定する必要がある。
デフォルト値は false

skip-verification
true の場合、ユーザーまたはコミット検証ステータスを検証しない。
デフォルト値は false。

---

output

PR の情報が各 output で確認できる。

dependency-names
この PR で更新されるすべてのパッケージ名のカンマ区切りリスト。

dependency-type
この PR が特定した依存関係の種類、例: "direct:production"。

update-type
この PR による最も大きなセマンティックバージョンの変更 (例: "version-update:semver-major")。

updated-dependencies-json
更新される各依存関係の完全な情報を含むJSON文字列。

directory
Dependabot による依存関係の更新の根拠となる directory 設定。

package-ecosystem
Dependabot による依存関係の更新の根拠となる package-ecosystem 設定。
…となっているが、package-ecosystem で npm と指定していても output では npm_and_yarn と返ってきたりと必ずしも dependabot.yml の設定値と完全一致はしていない模様…

target-branch
Dependabot による依存関係の更新の根拠となる target-branch 設定。

previous-version
この PR による更新前の依存関係のバージョン。

new-version
この PR による更新後の依存関係のバージョン。

alert-state
この PR が セキュリティアラートと関連していて(おそらく Dependabot security updates による PR でということだと思われる)、 alert-lookup が true の場合、その警告の現在の状態（OPEN / FIXED / DISMISSED）。

ghsa-id
この PR が セキュリティアラートと関連していて、 alert-lookup が true の場合、その警告の GHSA-ID。

cvss
この PR が セキュリティアラートと関連していて、 alert-lookup が true の場合、その警告のCVSS値（それ以外の場合は0）。

compatibility-score
この PR が既知の互換性スコアを持っていて、 compat-lookup が true の場合、その互換性スコア（それ以外の場合は0）。

maintainer-changes
この PR の本文に「Maintainer changes」というフレーズが含まれているか。これはメンテナが変更されたかどうかの指標。

---

参考:

その他 Tips

先輩から教えていただいたもの。

Dependabot による処理のログ

GitHub Actions の Dependabot という workflow から確認できる。Dependabot の設定を変更した後に、その設定がうまく反映されているかをここでチェックすることができる。

Dependabot version updates の手動実行

設定したスケジュールによる自動実行を待たずとも、以下の手順でパッケージマネージャ個別に手動実行可能。

対象リポジトリの Insights > Dependency graph > Dependabot > 対象パッケージマネージャのマニフェストの　Recent update jobs > check for updates

PR 最大数のバランス

多すぎると1つの PR をマージしたことで、他の PR で自動 rebase が実行され、これにより CI も自動実行される。無駄。
少なすぎると上限分の PR をマージしても、次回の自動の PR 作成が最速で翌日になるため、極論一生解決が追いつかなくなる可能性がある。

PR にはマメに対応する

ためてしまうと、PR の リリースノートの確認が大変になる。

参考