実際のプロセスに合わせて Dependabot pull request をカスタマイズする

実際の内部ワークフローに合わせて Dependabot pull request を調整する方法について説明します。

この機能を使用できるユーザーについて

Users with write access

この記事で

独自の内部プロセスに適するように、 Dependabot pull request をカスタマイズするさまざまな方法があります。

たとえば、 Dependabotのプル要求を CI/CD パイプラインに統合するために、 カスタム ラベル をプル要求に適用し、アクション ワークフローをトリガーするために使用できます。

複数のカスタマイズ オプションがあり、すべてを組み合わせて使って、パッケージ エコシステムごとに調整できます。

担当者の自動追加

既定では、 Dependabot は、割り当てユーザーなしでプル要求を発生させます。

指定したセキュリティ チームに pull request を自動的に割り当てるには、assignees を使ってパッケージ エコシステムごとにこれらの値を設定できます。

次の dependabot.yml ファイル例では、npm のバージョンおよびセキュリティ更新プログラムを使って開かれたすべての pull request が次のようになるように npm の構成を変更しています。

  • Pull request に自動的に割り当てられる個人 ("user-name")。
YAML
# `dependabot.yml` file with
#  assignee for all npm pull requests

version: 2
updates:
  # Keep npm dependencies up to date
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Raise all npm pull requests with assignees
    assignees:
      - "user-name"

レビュー担当者の自動追加

既定では、 Dependabot はレビュー担当者なしでプル要求を発生させます。

プロジェクトのセキュリティ更新プログラムが適切なチームによって迅速に対処されるように、CODEOWNERS ファイルを使用してレビュー担当者を Dependabot pull request に自動的に追加できます。 「コードオーナーについて」を参照してください。

カスタム ラベルを使って pull request にラベルを付ける

既定では、 Dependabot は、 dependencies ラベルを持つプル要求を発生させます。

Dependabot また、 java、 npm、 github-actionsなどのエコシステム ラベルをプル要求に適用します。 Dependabot では、フィルター処理とトリアージを向上させるために、単一エコシステムの更新を含むすべてのプル要求に、 dependencies ラベルとエコシステム ラベルの両方が追加されます。

Dependabot は、リポジトリにまだ存在しない場合にプル要求に適用される既定のラベルを作成します。 既定値ではなくカスタム ラベルを使用する場合は、パッケージ エコシステムごとに labels ファイルで dependabot.yml オプションを設定できます。これにより、既定値がオーバーライドされます。 詳細については、「ラベルを管理する」と labels を参照してください。

セマンティック バージョン (SemVer) ラベルがリポジトリに存在する場合、 Dependabot は、バージョン更新の種類 (major、 minor、または patch) を示すためにも自動的に適用されます。 これらのラベルは、定義したカスタム ラベルに加えて適用されます。

labels を使うと、既定のラベルをオーバーライドし、パッケージ エコシステムごとに独自のカスタム ラベルを指定できます。 これは、たとえば次のような場合に便利です。

  • ラベルを使って、特定の pull request に優先順位を割り当てます。
  • ラベルを使って、pull request をプロジェクト ボードに自動的に追加するなど、別のワークフローをトリガーします。

次の dependabot.yml ファイル例では、npm のバージョンおよびセキュリティ更新プログラムで開かれたすべての pull request にカスタム ラベルが割り当てられるように npm 構成を変更しています。

YAML
# `dependabot.yml` file with
# customized npm configuration

version: 2
updates:
  # Keep npm dependencies up to date
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Raise all npm pull requests with custom labels
    labels:
      - "npm dependencies"
      - "triage-board"

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

参照 labels.

コミット メッセージにプレフィックスを追加する

既定では、 Dependabot はコミット メッセージの基本設定を検出し、同様のパターンを使用しようとします。 さらに、 Dependabot はコミット メッセージに基づいてプル要求のタイトルを設定します。

特定のパッケージ エコシステムの Dependabotのコミット メッセージ (および pull request タイトル) には、独自のプレフィックスを指定できます。 これは、たとえば、コミット メッセージや pull request のタイトルを処理する自動化を実行している場合に便利です。

設定を明示的に指定するには、commit-message を次のサポートされているオプションと共に使います。

  • prefix:
    • すべてのコミット メッセージのプレフィックスを指定します。
    • Pull request のタイトルの先頭にもプレフィックスが追加されます。
  • prefix-development:
    • パッケージ マネージャーまたはエコシステムによって定義されているように、開発の依存関係を更新するすべてのコミット メッセージに個別のプレフィックスを指定します。
    • bundler、composer、mix、maven、npm、pip、およびuvでサポートされます。
  • include: "scope":
    • 任意のプレフィックスの後に、コミットで更新された依存関係の種類 (deps または deps-dev) が続くことを指定します。

次の例は、パッケージ エコシステムごとに調整された複数のオプションを示しています。

YAML
# Customize commit messages

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      # Prefix all commit messages with "npm: "
      prefix: "npm"

  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      # Prefix all commit messages with "[docker] " (no colon, but a trailing whitespace)
      prefix: "[docker] "

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "weekly"
    # Prefix all commit messages with "Composer" plus its scope, that is, a
    # list of updated dependencies
    commit-message:
      prefix: "Composer"
      include: "scope"

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    # Include a list of updated dependencies
    # with a prefix determined by the dependency group
    commit-message:
      prefix: "pip prod"
      prefix-development: "pip dev"

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

参照 commit-message.

Pull request とマイルストーンを関連付ける

マイルストーンは、プロジェクトの目標またはリリースに向けた pull request (または issue) のグループの進行状況を追跡するのに役立ちます。 Dependabotでは、milestone オプションを使用して、依存関係の更新に対するプル要求を特定のマイルストーンに関連付けることができます。

マイルストーンのラベルではなく、その数値識別子を指定する必要があります。 数値識別子を見つけるには、ページ URL の最後の部分 (milestone の後) をチェックします。 たとえば、https://github.com/<org>/<repo>/milestone/3、"3" はマイルストーンの数値識別子です。

YAML
# Specify a milestone for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Associate pull requests with milestone "4"
    milestone: 4

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

「milestone」と「マイルストーンについて」も参照してください。

プル リクエストのブランチ名のカスタマイズ

Dependabot は、プルリクエストごとにブランチを生成します。 各ブランチ名には、dependabot に加えて、パッケージ マネージャーの名前と更新対象の依存関係が含まれます。 既定では、ブランチ名のこれらの部分は、/ 記号で区切られています。次に例を示します。

  • dependabot/npm_and_yarn/next_js/acorn-6.4.1

pull-request-branch-name、separator、prefix、max-length、word-separator、branch-name-caseの各パラメーターを使用して、template オプションを使用してブランチ名をカスタマイズできます。 すべてのオプションは構成可能であり、任意のオプションを組み合わせることができます。 各パラメーターの完全なリファレンスについては、 pull-request-branch-nameを参照してください。

書式設定オプションの組み合わせ

separator、word-separator、branch-name-case、max-length、およびtemplateを組み合わせて、システムの要件を満たすブランチ名を生成できます。 たとえば、Docker タグの互換性、Azure Container Registryの名前付け、Kubernetes ブランチの長さの制限などです。

templateが他のオプションと共に設定されている場合、書式設定は、テンプレートのレンダリング後に、区切り記号の置換、単語区切り文字の置換、大文字と小文字の変換、最大長の切り捨てという順序で後処理として適用されます。

YAML
# Combine template with formatting options

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      template: "{prefix}/{package_manager}/{dependency}-{version}"
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
      max-length: 80
  • Before (default): dependabot/npm_and_yarn/Lodash-4.17.21
  • After (上記の構成を使用): dependabot-npm-and-yarn-lodash-4.17.21

ブランチ名が max-lengthを超えると、一意性を維持するためにハッシュ サフィックスで切り捨てられます。

マルチエコシステム グループの完全な例

次の dependabot.yml は、マルチエコシステム グループの構成など、さまざまなエコシステムで使用可能なすべてのオプションを示しています。

YAML
# Full example demonstrating all branch name options

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      template: "{prefix}/infra/{name}"
      word-separator: "-"
      branch-name-case: "lowercase"

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
    groups:
      frontend-deps:
        patterns: ["react*", "next*"]

  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "monthly"
    pull-request-branch-name:
      template: "{prefix}/{package_manager}/{dependency}-{version}"
      max-length: 60

  - package-ecosystem: "pip"
    directory: "/backend"
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      prefix: "deps"
      branch-name-case: "lowercase"
    groups:
      django-deps:
        patterns: ["django*"]

  # These entries participate in the "infrastructure" multi-ecosystem group
  - package-ecosystem: "docker"
    directory: "/infra"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"

  - package-ecosystem: "terraform"
    directory: "/infra"
    patterns: ["hashicorp/*"]
    multi-ecosystem-group: "infrastructure"

この構成では、次のブランチ名が生成されます。

シナリオ戦略ブランチ名
lodash npm の更新ソロdependabot-npm-and-yarn-lodash-4.17.21
npm の frontend-deps グループの更新グループ化dependabot-npm-and-yarn-frontend-deps-fc93691fd4
nginx 単体 Docker の更新ソロdependabot/docker/nginx-1.25.0
pip Django の更新ソロdeps/pip/django-4.2.1
pip django-deps グループの更新グループ化deps/pip/django-deps-a1b2c3d4e5
エコシステム間インフラストラクチャ グループ (Docker + Terraform)マルチエコシステムdependabot/infra/infrastructure-fc93691fd4

メモ

マルチエコシステム グループの場合: * pull-request-branch-nameエントリのmulti-ecosystem-groupsは、グループ化されたエコシステム間 PR ブランチ名を制御します。 * updatesを指定する個々のmulti-ecosystem-groupエントリは、独自の**** を持pull-request-branch-name。 グループ レベルの構成が優先され、これらのエントリに使用されるのは 1 つだけです。 * {package_manager} グループは複数のエコシステムにまたがるため、複数のエコシステム グループ テンプレートでは使用できません。

  • コンテンツ ダイジェストは常に、一意性を保証するために、複数のエコシステム グループブランチに自動的に追加されます。

ブランチ名の構成の適用方法

  • 構成は更新ごとのエントリです。スタンドアロン package-ecosystem エントリごとに、独自のブランチ名の構成を使用できます。 複数エコシステム グループに割り当てられたエントリでは、代わりにグループ レベルの構成が使用されます。
  • 既存の PR は影響を受けません。変更は、新しく作成された PR にのみ適用されます。
  • 既定の動作は変更されません。オプションを構成しない場合、ブランチ名は現在とまったく同じままです。

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

既定ではないブランチに対する pull request をターゲットに設定する

既定では、 Dependabot は既定のブランチでマニフェスト ファイルをチェックし、既定のブランチに対して更新のプル要求を発生させます。

一般に、 Dependabotのチェックと更新を既定のブランチに保持するのが最も理にかなっています。 ただし、場合によっては、別のターゲット ブランチを指定する必要があります。 たとえば、チームのプロセスで、最初に非運用ブランチで更新プログラムをテストして検証する必要がある場合は、 target-branch を使用して、プル要求を発生させる Dependabot に別のブランチを指定できます。

メモ

Dependabot は、既定のブランチに対してのみ、セキュリティ更新プログラムのプル リクエストを作成します。 target-branch を使うと、結果として、そのパッケージ マネージャーのすべての構成設定は、セキュリティ更新プログラムではなくバージョン更新プログラムに "のみ" 適用されます。__

YAML
# Specify a non-default branch for pull requests for pip

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    # Raise pull requests for version updates
    # to pip against the `develop` branch
    target-branch: "develop"
    # Labels on pull requests for version updates only
    labels:
      - "pip dependencies"

  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      # Check for npm updates on Sundays
      day: "sunday"
    # Labels on pull requests for security and version updates
    labels:
      - "npm dependencies"

参照 target-branch.