Dependency review

About dependency review

依存関係レビューを使うと、すべてのPull Reqeustにおける以下の変更による依存関係の変化とセキュリティについての影響を理解しやすくなります。pull request の [Files Changed](変更されたファイル) タブ上のリッチ diff で依存関係の変更をわかりやすく視覚化できます。 依存関係レビューは、以下のことを知らせます:

• リリース日と合わせて、追加、削除、更新された依存関係
• これらのコンポーネントを使うプロジェクトの数
• これらの依存関係に関する脆弱性のデータ

For pull requests that contain changes to package manifests or lock files, you can display a dependency review to see what has changed. The dependency review includes details of changes to indirect dependencies in lock files, and it tells you if any of the added or updated dependencies contain known vulnerabilities.

Sometimes you might just want to update the version of one dependency in a manifest and generate a pull request. However, if the updated version of this direct dependency also has updated dependencies, your pull request may have more changes than you expected. The dependency review for each manifest and lock file provides an easy way to see what has changed, and whether any of the new dependency versions contain known vulnerabilities.

By checking the dependency reviews in a pull request, and changing any dependencies that are flagged as vulnerable, you can avoid vulnerabilities being added to your project. For more information about how dependency review works, see プルリクエスト内の依存関係の変更をレビューする.

Dependabot alerts will find vulnerabilities that are already in your dependencies, but it's much better to avoid introducing potential problems than to fix problems at a later date. For more information about Dependabot alerts, see Dependabot alerts.

Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see 依存関係グラフがサポートされるパッケージ エコシステム.

For more information on supply chain features available on GitHub, see Supply chain security.

Enabling dependency review

The dependency review feature becomes available when you enable the dependency graph. For more information, see Enabling the dependency graph."

About the 依存関係レビュー アクション

"依存関係レビュー アクション" とは、GitHub Actions コンテキスト内の pull request の差異を報告できる特定のアクションです。 以下を参照してください。dependency-review-action リポジトリで 依存関係レビュー アクション を使って、pull request に依存関係レビューを適用できます。 このアクションは、pull request のパッケージ バージョンの変更によって発生した依存関係の脆弱なバージョンをスキャンし、関連するセキュリティの脆弱性について警告します。 これにより、pull request で何が変更されているかをより正確に把握でき、リポジトリに脆弱性が追加されるのを防ぐことができます。

既定では、脆弱性のあるパッケージが検出された場合、依存関係レビュー アクション チェックは失敗します。 リポジトリの所有者が依存関係レビューのチェックに合格することを要求している場合、チェックが失敗すると pull request のマージがブロックされます。 詳しくは、「保護されたブランチについて」をご覧ください。

The action is available for all public repositories, as well as private repositories that have GitHub Code Security or GitHub Advanced Security enabled.

組織の所有者は、組織内のリポジトリ全体で 依存関係レビュー アクション の使用を実施することで、依存関係レビューを大規模にロールアウトできます。 これには、必要なワークフローとして 依存関係レビュー アクション を設定するためのリポジトリ ルールセットの使用が含まれます。つまり、pull requestは、ワークフローが必要なすべてのチェックに合格した後にのみ統合できます。 詳しくは、「Enforcing dependency review across an organization」をご覧ください。

The action uses the dependency review REST API to get the diff of dependency changes between the base commit and head commit. You can use the dependency review API to get the diff of dependency changes, including vulnerability data, between any two commits on a repository. For more information, see 依存関係レビュー用の REST API エンドポイント. The action also considers dependencies submitted via the 依存関係送信 API. For more information about the 依存関係送信 API, see Using the dependency submission API.

You can configure the 依存関係レビュー アクション to better suit your needs. For example, you can specify the severity level that will make the action fail, or set an allow or deny list for licenses to scan. For more information, see Configuring the dependency review action.

Best practices for using the dependency review API and the 依存関係送信 API together

The dependency review API and the 依存関係レビュー アクション both work by comparing dependency changes in a pull request with the state of your dependencies in the head commit of your target branch.

If your repository only depends on statically defined dependencies in one of GitHub’s supported ecosystems, the dependency review API and the 依存関係レビュー アクション work consistently.

However, you may want your dependencies to be scanned during a build and then uploaded to the 依存関係送信 API. In this case, there are some best practices you should follow to ensure that you don’t introduce a race condition when running the processes for the dependency review API and the 依存関係送信 API, since it could result in missing data.

The best practices you should take will depend on whether you use GitHub Actions to access the 依存関係送信 API and the dependency review API, or whether you use direct API access.

Using GitHub Actions to access the 依存関係送信 API and the dependency review API

If you use GitHub Actions to access the 依存関係送信 API or the dependency review API:

• Make sure you run all of your dependency submission actions in the same GitHub Actions workflow as your 依存関係レビュー アクション. This will give you control over the order of execution, and it will ensure that dependency review will always work.
• If you do choose to run the 依存関係レビュー アクション separately, you should:
  • Set retry-on-snapshot-warnings to true.
  • Set retry-on-snapshot-warnings-timeout to slightly exceed the typical run time (in seconds) of your longest-running dependency submission action.

Using direct API access to the 依存関係送信 API and the dependency review API

If you don’t use GitHub Actions, and your code relies on direct access to the 依存関係送信 API and the dependency review API:

• Make sure you run the code that calls the 依存関係送信 API first, and then run the code that calls the dependency review API afterwards.
• If you do choose to run the code for the 依存関係送信 API and the dependency review API in parallel, you should implement a retry logic and note the following:
  • When there are snapshots missing for either side of the comparison, you will see an explanation for that in the x-github-dependency-graph-snapshot-warnings header (as a base64-encoded string). Therefore, if the header is non-empty, you should consider retrying.
  • Implement a retry logic with exponential backoff retries.
  • Implement a reasonable number of retries to account for the typical runtime of your dependency submission code.

Further reading

• Customizing your dependency review action configuration