Dependabot オプション リファレンス

dependabot.yml ファイルについて

dependabot.yml ファイルで、Dependabot がバージョン更新プログラムを使って依存関係を保持する方法を定義します。 さらに、 アイコンが表示されているいずれのオプションを使っても、Dependabot がセキュリティ更新プログラムに対する pull request の作成方法を変更できます。ただし、target-branch が使われている場合は除きます。

Dependabot の構成ファイルである dependabot.yml では、YAML 構文を使います。 YAML を初めて使う場合、詳細については、「Learn YAML in five minutes」(5 分で学ぶ YAML) を参照してください。

このファイルは、既定のブランチにリポジトリの .github ディレクトリに保存する必要があります。 dependabot.yml ファイルを追加または更新すると、バージョン更新の即時チェックがトリガーされます。 詳細と例については、「Dependabot のバージョン アップデートの設定」を参照してください。

必須のキー

必要に応じて、最上位レベルの registries キーを含めて、プライベート レジストリのアクセス詳細を定義することもできます。「最上位レベルの registries キー」を参照してください。

# Basic `dependabot.yml` file with
# minimum configuration for two package managers

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: "npm"
    # Look for `package.json` and `lock` files in the `root` directory
    directory: "/"
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: "daily"

  # Enable version updates for Docker
  - package-ecosystem: "docker"
    # Look for a `Dockerfile` in the `root` directory
    directory: "/"
    # Check for updates once a week
    schedule:
      interval: "weekly"

# Basic `dependabot.yml` file with
# minimum configuration for two package managers

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: "npm"
    # Look for `package.json` and `lock` files in the `root` directory
    directory: "/"
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: "daily"

  # Enable version updates for Docker
  - package-ecosystem: "docker"
    # Look for a `Dockerfile` in the `root` directory
    directory: "/"
    # Check for updates once a week
    schedule:
      interval: "weekly"

dependabot.yml ファイルの実際の例については、Dependabot 自体の構成ファイルのページを参照してください。

allow

パッケージ エコシステムに対してどの依存関係を保持するかを正確に定義するために使います。 多くの場合、ignore オプションと共に使われます。 例については、「Dependabot で更新する依存関係を制御する」を参照してください。

Dependabot の既定の動作:

• マニフェストで明示的に定義されたすべての依存関係は、バージョン更新プログラムによって最新の状態に保たれます。
• 脆弱な依存関係があるロック ファイルに定義されているすべての依存関係は、セキュリティ更新プログラムによって更新されます。

allow を指定した場合、Dependabot によって次のプロセスが使われます。

1. 明示的に許可した依存関係をすべてチェックします。

2. 次に、無視された依存関係またはバージョンを除外します。

   依存関係が allow と ignore ステートメントと一致する場合、依存関係は無視されます。

dependency-name (allow)

ほとんどのパッケージ マネージャーでは、ロックまたはマニフェスト ファイルで指定された依存関係名と一致する値を定義する必要があります。 一部のシステムには、より複雑な要件があります。

dependency-type (allow)

assignees

パッケージ エコシステムに対して生成されたすべての pull request に個別の担当者を指定します。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• Pull request は担当者なしで作成されます。

assignees が定義されている場合:

• バージョン更新プログラムのすべての pull request は、選んだ担当者を使って作成されます。
• target-branch で既定ではないブランチに対する更新プログラムを定義していない場合、セキュリティ更新プログラムのすべての pull request は、選んだ担当者を使って作成されます。

担当者はリポジトリへの書き込みアクセス権限を持っている必要があります。 Organization が所有するリポジトリの場合、読み取りアクセス権を持つ organization メンバーも有効な担当者です。

commit-message

コミット メッセージの形式を定義します。 Pull request のタイトルはコミット メッセージに基づいて記述されるため、この設定は pull request のタイトルにも影響します。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• コミット メッセージは、リポジトリで検出されたものと同様のパターンに従います。

commit-message が定義されている場合:

• すべてのコミット メッセージは、定義されたパターンに従います。
• target-branch で既定ではないブランチに対する更新プログラムを定義していない場合、すべてのコミット メッセージは定義されたパターンに従います。

prefix

• prefix-development も定義されていない場合、すべてのコミット メッセージに使われます。
• 値は最長 50 文字です。
• 値の末尾が文字、数字、終わり丸かっこ、または終わり角かっこである場合、メインのコミット メッセージを追加する前に、Dependabot によってプレフィックスの後にコロンが挿入されます。
• コロンの追加を停止するには、値の末尾を空白文字にします。

prefix-development

サポートしているもの: bundler、composer、mix、maven、npm、pip。

• Development 依存関係グループ内の依存関係を更新するコミット メッセージにのみ使われます。
• それ以外の場合、パラメーターは prefix パラメーターとまったく同じように動作します。

include

• 値 scope のみをサポートします
• 定義すると、プレフィックスの後にコミットで更新される依存関係の種類 (deps または deps-dev) が続きます。

directory

必須のオプション。 各パッケージ マネージャー (package.json や Gemfile など) のパッケージ マニフェストの場所を定義するために使用します。 この情報がないと、Dependabot ではバージョン更新プログラムの pull request を作成できません。 例については、「dependabot.yml ファイルの例」を参照してください。

• ほとんどのパッケージ マネージャーのリポジトリのルートに対して相対的なディレクトリを定義します。
• GitHub Actions には、値 / を使います。 Dependabot は、/.github/workflows ディレクトリとルート ディレクトリの action.yml/action.yaml ファイルを検索します。

構成ファイル内で複数のブロックを使ってエコシステムの 1 つのターゲット ブランチの更新を定義する必要がある場合は、すべての値が一意であり、定義したディレクトリに重複がないことを確認する必要があります。

enable-beta-ecosystems

現在使用できません。

ignore

パッケージ エコシステムに対してどの依存関係を保持するかを正確に定義するには、allow オプションと共に使います。 Dependabotは許可されたすべての依存関係をチェックし、それから無視された依存関係やバージョンをフィルタリングします。 そのため、許可と無視の両方と一致する依存関係は無視されます。 例については、「Dependabot で更新する依存関係を制御する」を参照してください。

Dependabot の既定の動作:

• マニフェストで明示的に定義されたすべての依存関係は、バージョン更新プログラムによって最新の状態に保たれます。
• 脆弱な依存関係があるロック ファイルに定義されているすべての依存関係は、セキュリティ更新プログラムによって更新されます。

ignore を使うと、Dependabot によって次のプロセスが使われます。

1. 明示的に許可した依存関係をすべてチェックします。

2. 次に、無視された依存関係またはバージョンを除外します。

   依存関係が allow と ignore ステートメントと一致する場合、依存関係は無視されます。

dependency-name (ignore)

ほとんどのパッケージ マネージャーでは、ロックまたはマニフェスト ファイルで指定された依存関係名と一致する値を定義する必要があります。 一部のシステムには、より複雑な要件があります。

versions (ignore)

特定のバージョンまたはバージョン範囲を無視するために使います。 範囲を定義する場合は、パッケージ マネージャーの標準パターンを使います。 次に例を示します。

• npm: ^1.0.0 を使います
• Bundler: ~> 2.0 を使います
• Docker: Ruby バージョン構文を使います
• NuGet: 7.* を使います

例については、「Dependabot で更新する依存関係を制御する」を参照してください。

update-types (ignore)

無視するセマンティック バージョン (SemVer) を指定します。 SemVer は、x.y.z の形式でソフトウェア パッケージのバージョンを定義するための標準として認められています。 Dependabot では、この形式のバージョンは常に major.minor.patch.

• パッチ リリースを含めるには、patch を使います。
• マイナー リリースを含めるには、minor を使います。
• メジャー リリースを含めるには、major を使います。

insecure-external-code-execution

サポート: bundler、mix、および pip。

更新時に、Dependabot がマニフェスト内の外部コードを実行できるようにします。 例については、「外部コードの実行を許可する」を参照してください。

Dependabot の既定の動作:

• Dependabot に 1 つ以上のレジストリへのアクセスを許可すると、侵害されたパッケージからコードを保護するために、外部コードの実行は自動的に無効になります。
• コードを実行できないと、バージョン更新プログラムが失敗する場合があります。

insecure-external-code-execution を許可する場合:

• Dependabot により、バージョン更新プログラム プロセスの一部としてマニフェスト内のコードが実行されます。
• コードは、その updates の設定に関連付けられたレジストリ内のパッケージ マネージャーにのみアクセスできます。 最上位の registries 構成で定義されているレジストリへのアクセスは許可されません。
• そのため、更新プログラムは成功するはずですが、侵害されたパッケージが資格情報を盗んだり、構成済みのレジストリにアクセスしたりする可能性もあります。

サポートされる値: allow。

labels

パッケージ マネージャーに対して発行されるすべての pull request に独自のラベルを指定します。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• すべての pull request には dependencies ラベルが付いています。
• 複数のパッケージ マネージャーを定義すると、エコシステムまたは言語の追加ラベルが各 pull request に追加されます。 例: Gradle の更新プログラムの場合は java、git サブモジュールの更新プログラムの場合は submodules です。
• Dependabotは、リポジトリ中の必要に応じて自動的にこれらのデフォルトラベルを作成します。

labels が定義されている場合:

• 指定したラベルは、既定のラベルの代わりに使われます。
• これらのラベルのいずれかがリポジトリで定義されていない場合は無視されます。
• labels: [ ] を使うと、既定のラベルを含むすべてのラベルを無効にできます。

target-branch を使って既定以外のブランチのバージョン アップデートをチェックしないかぎり、このオプションの設定も、このパッケージ マネージャーのマニフェスト ファイルに対するセキュリティ更新プログラムの pull request に影響します。

milestone

パッケージ マネージャーに対して生成されたすべての pull request をマイルストーンに関連付けます。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• マイルストーンは使われません。

milestone が定義されている場合:

• パッケージ マネージャーに対するすべての pull request がマイルストーンに追加されます。

サポートされる値: マイルストーンの数値識別子。

open-pull-requests-limit

開いているバージョン更新プログラムの pull request の最大数に関する制限はいつでも変更できます。

Dependabot の既定の動作:

• バージョン更新プログラムを含む pull request が 5 つ開いている場合、それらの開いている request の一部がマージまたは終了されるまで、それ以上の pull request は生成されません。
• セキュリティ更新プログラムには、開いている pull request は 10 件という別の内部制限があり、変更できません。

open-pull-requests-limit が定義されている場合:

• Dependabot により、定義した整数値までの pull request が開かれます。
• このオプションを 0 に設定すると、パッケージ マネージャーのバージョン更新プログラムを一時的に無効にできます。「Dependabot version updates を無効にする」を参照してください。

package-ecosystem

必須のオプション。 Dependabot で新しいバージョンを監視するパッケージ マネージャーごとに、package-ecosystem 要素を 1 つ定義します。 リポジトリには、各パッケージ マネージャーの依存関係マニフェストまたはロック ファイルも含める必要があります。「dependabot.yml ファイルの例」を参照してください。

pull-request-branch-name.separator

ブランチ名の生成時に使う区切り記号を指定します。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• 次の形式のブランチ名を生成します: dependabot/PACKAGE_MANAGER/DEPENDENCY

pull-request-branch-name.separator が定義されている場合:

• / ではなく指定した文字を使います。

サポートされる値: "-"、_、/

rebase-strategy

Dependabot によって生成された pull request の自動リベースを無効にします。

Dependabot の既定の動作は、Dependabot がバージョンまたはセキュリティ更新プログラムの pull request に対する変更を検出したときに、開いている pull request をリベースすることです。 次の場合、Dependabot によって変更がチェックされます。

• バージョン更新プログラムをチェックするスケジュールが実行される。
• 終了した Dependabot pull request を再度開く。
• Dependabot 構成ファイル内の target-branch の値を変更する (「target-branch」を参照してください)。
• ターゲット ブランチへの最近のプッシュ後に、Dependabot pull request に競合が発生した。

rebase-strategy が disabled に設定されている場合、Dependabot では pull request のリベースを停止します。

registries

Dependabot がより広範囲の依存関係を更新できるように、プライベート パッケージ レジストリへのアクセスを構成します。「Dependabot のプライベート レジストリへのアクセスの構成」と「Dependabot のプライベート レジストリの構成に関するガイダンス」を参照してください。

dependabot.yml ファイルには、registries キーを使用できる場所が 2 つあります。

1. 最上位レベルには、使うプライベート レジストリとそのアクセス情報を定義します。「Dependabot のプライベート レジストリへのアクセスの構成」を参照してください。
2. updates ブロック内で、各パッケージ マネージャーが使うプライベート レジストリを指定できます。

Dependabot の既定の動作では、パブリックにアクセスできるレジストリに格納されている依存関係を更新する場合にのみ、pull request を生成します。

Dependabot 構成ファイルに、1 つ以上のプライベート レジストリへのアクセスを定義する最上位レベルの registries セクションがある場合、これらのプライベート レジストリの 1 つ以上を使うように各 package-ecosystem を構成できます。

registries がパッケージ マネージャーに対して定義されている場合:

• パッケージ マネージャーに指定された各プライベート レジストリのバージョンとセキュリティの更新がチェックされます。
• 最上位レベルの registries セクションで定義されたアクセスの詳細が Dependabot によって使われます。

サポートされる値: REGISTRY_NAME または "*"

reviewers

パッケージ マネージャーに対して生成されたすべての pull request に、個々のレビュー担当者またはレビュー担当者のチームを指定します。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• レビュー担当者が割り当てられていない pull request が作成されます。

reviewers が定義されている場合:

• バージョン更新プログラムのすべての pull request は、選んだレビュー担当者によって作成されます。
• target-branch で既定ではないブランチに対する更新プログラムを定義していない場合、セキュリティ更新プログラムのすべての pull request は、選んだレビュー担当者を使って作成されます。

レビュー担当者は、少なくともそのリポジトリに対する読み取りアクセス権を持っている必要があります。

schedule

必須のオプション。 interval パラメーターを使って、構成する各パッケージ マネージャーの新しいバージョンをチェックする頻度を定義します。 必要に応じて、日単位と週単位の間隔で、Dependabot で更新プログラムをチェックするタイミングをカスタマイズできます。

interval

サポートされる値: daily、weekly、または monthly

各パッケージ マネージャーでスケジュール間隔を定義する必要があります。

• 月曜日から金曜日までの平日に実行するには、daily を使います。
• 週 1 回 (既定では月曜日) 実行するには、weekly を使います。
• 毎月 1 日に実行するには、monthly を使います。

デフォルトでは、Dependabotは設定ファイル中のすべての更新を適用する時間をランダムに割り当てます。 すべての間隔に特定のランタイムを設定するには、time および timezone パラメーターを使用できます。

day

サポートされる値: monday、tuesday、wednesday、thursday、friday、saturday、またはsunday

必要に応じて、特定の曜日にパッケージ マネージャーの更新プログラムを毎週実行します。

time

形式: hh:mm

必要に応じて、パッケージ マネージャーのすべての更新プログラムを特定の時間に実行します。 既定では、時刻は UTC として解釈されます。

timezone

time 値のタイム ゾーンを指定します。

タイム ゾーン識別子は、iana によって管理されているデータベース内のタイム ゾーンと同じにする必要があります。「List of tz database time zones」(tz データベースのタイム ゾーン一覧) を参照してください。

target-branch

バージョン更新プログラムをチェックし、バージョン更新プログラムの pull request をターゲットにするように特定のブランチを定義します。 例については、「実際のプロセスに合わせて Dependabot pull request をカスタマイズする」を参照してください。

Dependabot の既定の動作:

• Dependabot によって、リポジトリの既定のブランチが使われます。「既定のブランチについて」を参照してください。

target-branch が定義されている場合:

• バージョン更新プログラムがチェックされるのは、ターゲット ブランチ上のマニフェスト ファイルのみです。
• バージョン更新プログラムのすべての pull request は、指定したブランチを対象として開かれます。
• この package-ecosystem に対して定義されたオプションはセキュリティ更新プログラムには適用されなくなります。セキュリティ更新プログラムには、常にリポジトリの既定のブランチが使われるためです。

vendor

サポートしているもの: bundler と gomod のみ。

ベンダリングされた依存関係と、マニフェスト ファイルで定義された依存関係を保持するように Dependabot に指示します。 コードをリポジトリ内に格納すると、依存関係は "ベンダリングされている" または "キャッシュされている" と記述されます。bundle cache ドキュメントと go mod vendor ドキュメントを参照してください。

例については、「Dependabot で更新する依存関係を制御する」を参照してください。

Dependabot の既定の動作:

• マニフェストに記録された依存関係のみを保持し、Bundler 用として識別されたファイルをロックします。
• マニフェストとロック ファイルに記録されているバージョン番号を更新する、セキュリティおよびバージョン更新プログラムの pull request を生成します。
• Go モジュールの場合、ベンダリングされた依存関係はすべて、vendor が有効になっているかのように自動的に特定され、保持されます。

vendor が有効な場合:

• Dependabot により、リポジトリの _vendor/cache_ ディレクトリに格納されている Bundler の依存関係も保持されます。
• Pull request には、リポジトリに格納されている依存関係の更新が含まれる場合があります。

サポートされる値: true または false

versioning-strategy

サポートしているもの: bundler、cargo、composer、mix、npm、pip、pub

Dependabot でマニフェスト ファイルを編集する方法を定義します。 例については、「Dependabot で更新する依存関係を制御する」を参照してください。

Dependabot の既定の動作:

• アプリとライブラリの依存関係を区別するようにしてください。
• アプリの場合は、新しいバージョンに合わせて最小バージョン要件を常に引き上げてください。 increase 戦略。
• ライブラリの場合は、可能であれば、新旧両方のバージョンを含むように、許可するバージョン要件を広げます。 widen 戦略。

versioning-strategy を定義した場合、その指定した戦略が Dependabot によって使われます。

たとえば、現在のバージョンが 1.0.0 であり、現在の制約が ^1.0.0 の場合、複数の戦略によって次の更新が行われます。

新しいバージョン 1.2.0

• increase: 新しい制約 ^1.2.0
• increase-if-necessary: 新しい制約 ^1.0.0
• widen: 新しい制約 ^1.0.0

新しいバージョン 2.0.0

• increase: 新しい制約 ^2.0.0
• increase-if-necessary: 新しい制約 ^2.0.0
• widen: 新しい制約 >=1.0.0 <3.0.0

最上位レベルの registries キー

Dependabot が、プライベート パッケージ レジストリ (GitLab または Bitbucket でホストされているレジストリなど) にアクセスするために使用できる認証の詳細を指定します。

registries キーの値は連想配列で、その各要素は、特定のレジストリを指定するキーと、そのレジストリへのアクセスに必要な設定を指定する連想配列の値により構成されます。 次の dependabot.yml ファイルでは、ファイルの registries セクションで dockerhub として指定されたレジストリが構成された後、ファイルの updates セクションでそれが参照されています。

# Minimal settings to update dependencies stored in one private registry

version: 2
registries:
  dockerhub: # Define access for a private registry
    type: docker-registry
    url: registry.hub.docker.com
    username: octocat
    password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
  - package-ecosystem: "docker"
    directory: "/docker-registry/dockerhub"
    registries:
      - dockerhub # Allow version updates for dependencies in this registry
    schedule:
      interval: "monthly"

# Minimal settings to update dependencies stored in one private registry

version: 2
registries:
  dockerhub: # Define access for a private registry
    type: docker-registry
    url: registry.hub.docker.com
    username: octocat
    password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
  - package-ecosystem: "docker"
    directory: "/docker-registry/dockerhub"
    registries:
      - dockerhub # Allow version updates for dependencies in this registry
    schedule:
      interval: "monthly"

以下のオプションを使用して、アクセス設定を指定します。 レジストリの設定には、type と url、そして通常は username と password の組み合わせまたは token を含める必要があります。

使用可能なオプションの詳細と、プライベート レジストリを構成するときの推奨事項とアドバイスについては、「Dependabot のプライベート レジストリの構成に関するガイダンス」を参照してください。

type と認証の詳細

プライベート レジストリにアクセスするための認証の詳細を指定するために使われるパラメーターは、レジストリ type によって異なります。

認証に使われるすべての機密データを安全に格納し、その安全な場所から参照する必要があります。「Dependabot のプライベート レジストリへのアクセスの構成」を参照してください。

url および replaces-base

url パラメーターを使って、レジストリにアクセスする場所を定義します。 省略可能な replaces-base パラメーターが有効な場合 (true)、Dependabot により、その特定のエコシステムのベース URL ではなく、url の値を使って依存関係が解決されます。