About dependency review
Dependency review helps you understand dependency changes and the security impact of these changes at every pull request. It provides an easily understandable visualization of dependency changes with a rich diff on the "Files Changed" tab of a pull request. Dependency review informs you of:
- Which dependencies were added, removed, or updated, along with the release dates.
- How many projects use these components.
- Vulnerability data for these dependencies.
For more information, see "About dependency review" and "Reviewing dependency changes in a pull request."
About configuring dependency review
Dependency review is available when dependency graph is enabled for your GitHub Enterprise Server instance and Advanced Security is enabled for the organization or repository. For more information, see "Enabling GitHub Advanced Security for your enterprise."
Checking if the dependency graph is enabled
-
On your GitHub Enterprise Server instance, navigate to the main page of the repository.
-
Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
-
In the "Security" section of the sidebar, click Code security and analysis.
-
Under "Configure security and analysis features", check if the dependency graph is enabled.
-
If dependency graph is enabled, click Enable next to "GitHub Advanced Security" to enable Advanced Security, including dependency review. The enable button is disabled if your enterprise has no available licenses for Advanced Security.
About configuring the dependency review action
The dependency review action scans your pull requests for dependency changes and raises an error if any new dependencies have known vulnerabilities. The action is supported by an API endpoint that compares the dependencies between two revisions and reports any differences.
For more information about the action and the API endpoint, see the dependency-review-action
documentation, and "Dependency review" in the API documentation.
The following configuration options are available.
Option | Required | Usage |
---|---|---|
fail-on-severity | Defines the threshold for level of severity (low , moderate , high , critical ).The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | |
allow-ghsas | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. You can find the possible values for this parameter in the GitHub Advisory Database. | |
config-file | Specifies a path to a configuration file. The configuration file can be local to the repository or a file located in an external repository. | |
external-repo-token | Specifies a token for fetching the configuration file, if the file resides in a private external repository. The token must have read access to the repository. |
Configuring the dependency review action
There are two methods of configuring the dependency review action:
- Inlining the configuration options in your workflow file.
- Referencing a configuration file in your workflow file.
Notice that all of the examples use a short version number for the action (v3
) instead of a semver release number (for example, v3.0.8
). This ensures that you use the most recent minor version of the action.
Using inline configuration to set up the dependency review action
-
Add a new YAML workflow to your
.github/workflows
folder.For
runs-on
, the default label isself-hosted
. You can replace the default label with the label of any of your runners.YAML name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: self-hosted steps: - name: 'Checkout Repository' uses: actions/checkout@v4 - name: Dependency Review uses: actions/dependency-review-action@v3
name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: self-hosted steps: - name: 'Checkout Repository' uses: actions/checkout@v4 - name: Dependency Review uses: actions/dependency-review-action@v3
-
Specify your settings.
This dependency review action example file illustrates how you can use the available configuration options.
YAML name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: self-hosted steps: - name: 'Checkout Repository' uses: actions/checkout@v4 - name: Dependency Review uses: actions/dependency-review-action@v3 with: # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical # ([String]). Skip these GitHub Advisory Database IDs during detection (optional) # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679
name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: self-hosted steps: - name: 'Checkout Repository' uses: actions/checkout@v4 - name: Dependency Review uses: actions/dependency-review-action@v3 with: # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical # ([String]). Skip these GitHub Advisory Database IDs during detection (optional) # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679
Using a configuration file to set up dependency review action
-
Add a new YAML workflow to your
.github/workflows
folder and useconfig-file
to specify that you are using a configuration file.For
runs-on
, the default label isself-hosted
. You can replace the default label with the label of any of your runners.YAML name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: self-hosted steps: - name: 'Checkout Repository' uses: actions/checkout@v4 - name: Dependency Review uses: actions/dependency-review-action@v3 with: # ([String]). Representing a path to a configuration file local to the repository or in an external repository. # Possible values: An absolute path to a local file or an external file. config-file: './.github/dependency-review-config.yml' # Syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH config-file: 'github/octorepo/dependency-review-config.yml@main' # ([Token]) Use if your configuration file resides in a private external repository. # Possible values: Any GitHub token with read access to the private external repository. external-repo-token: 'ghp_123456789abcde'
name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: self-hosted steps: - name: 'Checkout Repository' uses: actions/checkout@v4 - name: Dependency Review uses: actions/dependency-review-action@v3 with: # ([String]). Representing a path to a configuration file local to the repository or in an external repository. # Possible values: An absolute path to a local file or an external file. config-file: './.github/dependency-review-config.yml' # Syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH config-file: 'github/octorepo/dependency-review-config.yml@main' # ([Token]) Use if your configuration file resides in a private external repository. # Possible values: Any GitHub token with read access to the private external repository. external-repo-token: 'ghp_123456789abcde'
-
Create the configuration file in the path you have specified.
This YAML example file illustrates how you can use the available configuration options.
YAML # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical # ([String]). Skip these GitHub Advisory Database IDs during detection (optional) # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories allow-ghsas: - GHSA-abcd-1234-5679 - GHSA-efgh-1234-5679
# Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical # ([String]). Skip these GitHub Advisory Database IDs during detection (optional) # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories allow-ghsas: - GHSA-abcd-1234-5679 - GHSA-efgh-1234-5679
For further details about the configuration options, see dependency-review-action
.