--- title: Configuring the dependency review action shortTitle: Configure dependency review action intro: You can use the {% data variables.dependency-review.action_name %} to catch vulnerabilities before they are added to your project. permissions: '{% data reusables.permissions.security-repo-enable %}' versions: fpt: '*' ghes: '*' ghec: '*' type: how_to topics: - Code Security - Dependency review - Vulnerabilities - Dependencies - Pull requests redirect_from: - /code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review --- ## About the {% data variables.dependency-review.action_name %} The "{% data variables.dependency-review.action_name %}" refers to the specific action that can report on differences in a pull request within the {% data variables.product.prodname_actions %} context, and add enforcement mechanisms to the {% data variables.product.prodname_actions %} workflow. {% data reusables.dependency-review.dependency-review-action-overview %} {% data reusables.dependency-review.org-level-enforcement %} Here is a list of common configuration options. For more information, and a full list of options, see [Dependency Review](https://github.com/marketplace/actions/dependency-review) on the {% data variables.product.prodname_marketplace %}. | Option | Required | Usage | |------------------|-------------------------------|--------| | `fail-on-severity` | {% octicon "x" aria-label="Optional" %} | 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. | | {% ifversion dependency-review-action-licenses %} | | `allow-licenses` | {% octicon "x" aria-label="Optional" %} | Contains a list of allowed licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.
The action will fail on pull requests that introduce dependencies with licenses that do not match the list.| | {% endif %} | | {% ifversion dependency-review-action-licenses %} | | `deny-licenses` | {% octicon "x" aria-label="Optional" %} | Contains a list of prohibited licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.
The action will fail on pull requests that introduce dependencies with licenses that match the list.| | {% endif %} | | `fail-on-scopes` | {% octicon "x" aria-label="Optional" %} | Contains a list of strings representing the build environments you want to support (`development`, `runtime`, `unknown`).
The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list.| | `comment-summary-in-pr` | {% octicon "x" aria-label="Optional" %} | Enable or disable the reporting of the review summary as a comment in the pull request. If enabled, you must give the workflow or job the `pull-requests: write` permission. With each execution, a new comment will overwrite the existing one.| | `allow-ghsas` | {% octicon "x" aria-label="Optional" %} | Contains a list of {% data variables.product.prodname_advisory_database %} IDs that can be skipped during detection. You can find the possible values for this parameter in the [{% data variables.product.prodname_advisory_database %}](https://github.com/advisories). | | `config-file` | {% octicon "x" aria-label="Optional" %} | 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` | {% octicon "x" aria-label="Optional" %} | 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.| {% ifversion dependency-review-action-licenses %} > [!TIP] > The `allow-licenses` and `deny-licenses` options are mutually exclusive. ## Configuring the {% data variables.dependency-review.action_name %} There are two methods of configuring the {% data variables.dependency-review.action_name %}: * 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 {% data variables.dependency-review.action_name %} 1. Add a new YAML workflow to your `.github/workflows` folder. {% ifversion ghes %}For `runs-on`, the default label is `self-hosted`. You can replace the default label with the label of any of your runners.{% endif %} ```yaml copy name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} steps: - name: 'Checkout Repository' uses: {% data reusables.actions.action-checkout %} - name: Dependency Review uses: actions/dependency-review-action@v4 ``` 1. Specify your settings. This {% data variables.dependency-review.action_name %} example file illustrates how you can use the available configuration options. ```yaml copy name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} steps: - name: 'Checkout Repository' uses: {% data reusables.actions.action-checkout %} - name: Dependency Review uses: actions/dependency-review-action@v4 with: # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical {% ifversion dependency-review-action-licenses %} # You can only include one of these two options: `allow-licenses` and `deny-licenses` # ([String]). Only allow these licenses (optional) # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ allow-licenses: GPL-3.0, BSD-3-Clause, MIT # ([String]). Block the pull request on these licenses (optional) # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ deny-licenses: LGPL-2.0, BSD-2-Clause {% endif %} # ([String]). Skip these {% data variables.product.prodname_advisory_database %} IDs during detection (optional) # Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679 # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional) # Possible values: "development", "runtime", "unknown" fail-on-scopes: development, runtime ``` ### Using a configuration file to set up {% data variables.dependency-review.action_name %} 1. Add a new YAML workflow to your `.github/workflows` folder and use `config-file` to specify that you are using a configuration file. {% ifversion ghes %}For `runs-on`, the default label is `self-hosted`. You can replace the default label with the label of any of your runners.{% endif %} ```yaml copy name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} steps: - name: 'Checkout Repository' uses: {% data reusables.actions.action-checkout %} - name: Dependency Review uses: actions/dependency-review-action@v4 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' # Optional alternative syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH (uncomment if preferred) # 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' ``` 1. Create the configuration file in the path you have specified. This YAML example file illustrates how you can use the available configuration options. ```yaml copy # Possible values: "critical", "high", "moderate", "low" fail-on-severity: critical {% ifversion dependency-review-action-licenses %} # You can only include one of these two options: `allow-licenses` and `deny-licenses` # ([String]). Only allow these licenses (optional) # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ allow-licenses: - GPL-3.0 - BSD-3-Clause - MIT # ([String]). Block the pull request on these licenses (optional) # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ deny-licenses: - LGPL-2.0 - BSD-2-Clause {% endif %} # ([String]). Skip these {% data variables.product.prodname_advisory_database %} IDs during detection (optional) # Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories allow-ghsas: - GHSA-abcd-1234-5679 - GHSA-efgh-1234-5679 # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional) # Possible values: "development", "runtime", "unknown" fail-on-scopes: - development - runtime ``` For further details about the configuration options, see [`dependency-review-action`](https://github.com/actions/dependency-review-action#readme). {% endif %} ## Further reading * [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration)