diff --git a/README.md b/README.md index 27216d526..b1d0d1184 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ raise an error if any vulnerabilities or invalid licenses are being introduced. The action is available for all public repositories, as well as private repositories that have GitHub Advanced Security licensed. -You can see the results on the job logs +You can see the results on the job logs: Screen Shot 2022-03-31 at 1 10 51 PM -or on the job summary +or on the job summary: @@ -33,7 +33,7 @@ jobs: - name: 'Checkout Repository' uses: actions/checkout@v3 - name: 'Dependency Review' - uses: actions/dependency-review-action@v2 + uses: actions/dependency-review-action@v3 ``` ### GitHub Enterprise Server @@ -59,183 +59,34 @@ jobs: - name: 'Checkout Repository' uses: actions/checkout@v3 - name: 'Dependency Review' - uses: actions/dependency-review-action@v2 + uses: actions/dependency-review-action@v3 ``` -## Configuration +## Configuration options -Configure this action by either using an external configuration file, -or by inlining these options in your workflow file. +Configure this action by either inlining these options in your workflow file, or by using an external configuration file. All configuration options are optional. -## Configuration Options +| Option | Usage | Possible values | Default value | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------| +| `fail-on-severity` | Defines the threshold for the level of severity. The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | `low`, `moderate`, `high`, `critical` | `low` | +| `allow-licenses`* | Contains a list of allowed licenses. The action will fail on pull requests that introduce dependencies with licenses that do not match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | +| `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | +| `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. |`runtime`, `development`, `unknown` | `runtime` | +| `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | +| `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `true` | +| `vulnerability-check` | Enable or disable the vulnerability check performed by the action. | `true`, `false` | `true` | +| `base-ref`/`head-ref` | Provide custom git references for the git base/head when performing the comparison check. This is only used for event types other than `pull_request` and `pull_request_target`. | Any valid git ref(s) in your project | none | -### config-file +*not supported for use with GitHub Enterprise Server -A string representing the path to a configuraton file. It can be a -local file, or a file located in an external repository. You can use -this syntax for external repositories: `OWNER/REPOSITORY/FILENAME@BRANCH`. +†will be supported with GitHub Enterprise Server 3.8 -If the configuration file is located in an external private repository, -use the [external-repo-token](#external-repo-token) parameter of the -action to specify a token that has read access to the repository. - -**Possible values**: A string representing a path to a file located -in the current repository, or in an external one. - -**Example**: `config-file: ./.github/dependency-review-config.yml # local file`. - -**Example**: `config-file: github/octorepo/dependency-review-config.yml@main # external repo` - -### fail-on-severity - -Configure the severity level for alerting. See "[Vulnerability Severity](https://github.com/actions/dependency-review-action#vulnerability-severity)". - -**Possible values**: `critical`, `high`, `moderate`, `low`. - -**Example**: `fail-on-severity: moderate`. - -### fail-on-scopes - -A list of strings representing the build environments you want to -support. The default value is `development, runtime`. - -**Possible values**: `development`, `runtime`, `unknown` - -**Inline example**: `fail-on-scopes: development, runtime` - -**YAML example**: - -```yaml -# this prevents scanning development dependencies -fail-on-scopes: - - runtime -``` - -### allow-licenses - -Only allow the licenses that comply with the expressions in this list. See "[Licenses](https://github.com/actions/dependency-review-action#licenses)". - -**Possible values**: A list of of [SPDX-compliant license identifiers](https://spdx.org/licenses/). - -**Inline example**: `allow-licenses: BSD-3-Clause, LGPL-2.1 OR MIT OR BSD-3-Clause` - -**YAML example**: - -```yaml -allow-licenses: - - BSD-3-Clause - - LGPL-2.1 - - MIT - - BSD-3-Clause -``` - -### deny-licenses - -Add a custom list of licenses you want to block. See -"[Licenses](https://github.com/actions/dependency-review-action#licenses)". - -**Possible values**: Any valid set of [SPDX licenses](https://spdx.org/licenses/). - -**Inline example**: `deny-licenses: LGPL-2.0, GPL-2.0+ WITH Bison-exception-2.2` - -**YAML example**: - -```yaml -deny-licenses: - - LGPL-2.0 - - GPL-2.0+ WITH Bison-exception-2.2 -``` - -### allow-ghsas - -A list of GitHub Security Advisory IDs that can be skipped during detection. - -**Possible values**: Any valid GHSAs from the [GitHub Advisory Database](https://github.com/advisories). - -**Inline example**: `allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679` - -**YAML example**: - -```yaml -allow-ghsas: - - GHSA-abcd-1234-5679 - - GHSA-efgh-1234-5679 -``` - -### license-check/vulnerability-check - -Disable the license checks or vulnerability checks performed by this Action. -You can't disable both checks. - -**Possible values**: `true` or `false` - -**Example**: - -```yaml -license-check: true -vulnerability-check: false -``` - -### base-ref/head-ref - -Provide custom git references for the git base/head when performing -the comparison. If you are using pull requests, or -`pull_request_target` events you do not need to worry about setting -this. The values need to be specified for all other event types. - -**Possible values**: Any valid git ref(s) in your project. - -**Example**: - -```yaml -base-ref: 8bb8a58d6a4028b6c2e314d5caaf273f57644896 -head-ref: 69af5638bf660cf218aad5709a4c100e42a2f37b -``` - -### external-repo-token - -A token for fetching external configuration files if they live in -an external private repository. - -Visit the [developer settings](https://github.com/settings/tokens) to -create a new personal access token with `read` permissions for the -repository that hosts the config file. - -**Possible values**: Any GitHub token with read access to the external repository. - -**Example**: `external-repo-token: ghp_123456789abcdef...` - -### Configuration File - -You can use an external configuration file to specify the settings for -this Action. - -Start by specifying that you will be using an external configuration -file: - -```yaml -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - config-file: './.github/dependency-review-config.yml' -``` - -And then create the file in the path you just specified. **All of these fields are -optional**: - -```yaml -fail-on-severity: 'critical' -allow-licenses: - - 'GPL-3.0' - - 'BSD-3-Clause' - - 'MIT' -``` ### Inline Configuration -You can pass options to the Dependency Review -Action using your workflow file. Here's an example of what the full -file would look like: +You can pass options to the Dependency Review GitHub Action using your workflow file. + +#### Example ```yaml name: 'Dependency Review' @@ -249,7 +100,7 @@ jobs: - name: 'Checkout Repository' uses: actions/checkout@v3 - name: Dependency Review - uses: actions/dependency-review-action@v2 + uses: actions/dependency-review-action@v3 with: fail-on-severity: moderate @@ -257,71 +108,41 @@ jobs: deny-licenses: LGPL-2.0, BSD-2-Clause ``` -### Vulnerability Severity +### Configuration File -By default the action will fail on any pull request that contains a -vulnerable dependency, regardless of the severity level. You can override this behavior by -using the `fail-on-severity` option, which will cause a failure on any pull requests that introduce vulnerabilities of the specified severity level or higher. The possible values are: `critical`, `high`, `moderate`, or `low`. The -action defaults to `low`. +You can use an external configuration file to specify the settings for this action. It can be a local file or a file in an external repository. Refer to the following options for the specification. -This example will only fail on pull requests with `critical` and `high` vulnerabilities: +| Option | Usage | Possible values | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| `config-file` | A path to a file in the current repository or an external repository. Use this syntax for external files: `OWNER/REPOSITORY/FILENAME@BRANCH` | **Local file**: `./.github/dependency-review-config.yml`
**External repo**: `github/octorepo/dependency-review-config.yml@main` | +| `external-repo-token` | Specifies a token for fetching the configuration file if the file resides in a private external repository. Create a token in [developer settings](https://github.com/settings/tokens). | Any token with `read` permissions to the repository hosting the config file. | -```yaml -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - fail-on-severity: high -``` +#### Example -### Dependency Scoping - -By default the action will only fail on `runtime` dependencies that have vulnerabilities or unacceptable licenses, ignoring `development` dependencies. You can override this behavior with the `fail-on-scopes` option, which will allow you to list the specific dependency scopes you care about. The possible values are: `unknown`, `runtime`, and `development`. Note: Filtering by scope will not be supported on Enterprise Server just yet, as the REST API's introduction of `scope` will be released in an upcoming Enterprise Server version. We will treat all dependencies on Enterprise Server as having a `runtime` scope and thus will not be filtered away. +Start by specifying that you will be using an external configuration file: ```yaml - name: Dependency Review uses: actions/dependency-review-action@v2 with: - fail-on-scopes: runtime, development + config-file: './.github/dependency-review-config.yml' ``` -### Licenses - -You can set the action to fail on pull requests based on the licenses of the dependencies -they introduce. With `allow-licenses` you can define the list of licenses -your repository will accept. Alternatively, you can use `deny-licenses` to only -forbid a subset of licenses. These options are not supported on Enterprise Server. - -You can use the [Licenses -API](https://docs.github.com/en/rest/licenses) to see the full list of -supported licenses. Use [SPDX licenses](https://spdx.org/licenses/) -to filter the licenses. A couple of examples: - -```yaml -# only allow MIT-licensed dependents -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - allow-licenses: MIT -``` +And then create the file in the path you just specified: ```yaml -# Block Apache 1.1 and 2.0 licensed dependents -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - deny-licenses: Apache-1.1+ +fail-on-severity: 'critical' +allow-licenses: + - 'GPL-3.0' + - 'BSD-3-Clause' + - 'MIT' ``` ### Considerations - Checking for licenses is not supported on Enterprise Server. -- The action will only accept one of the two parameters; an error will - be raised if you provide both. -- By default both parameters are empty (no license checking is - performed). -- We don't have license information for all of your dependents. If we - can't detect the license for a dependency **we will inform you, but the - action won't fail**. +- The action will only accept one of the two `license` parameters; an error will be raised if you provide both. +- We don't have license information for all of your dependents. If we can't detect the license for a dependency **we will inform you, but the action won't fail**. ## Blocking pull requests @@ -329,14 +150,11 @@ The Dependency Review GitHub Action check will only block a pull request from be ## Getting help -If you have bug reports, questions or suggestions please [create a new -issue](https://github.com/actions/dependency-review-action/issues/new/choose). +If you have bug reports, questions or suggestions please [create a new issue](https://github.com/actions/dependency-review-action/issues/new/choose). ## Contributing -We are grateful for any contributions made to this project. - -Please read [CONTRIBUTING.MD](https://github.com/actions/dependency-review-action/blob/main/CONTRIBUTING.md) to get started. +We are grateful for any contributions made to this project. Please read [CONTRIBUTING.MD](https://github.com/actions/dependency-review-action/blob/main/CONTRIBUTING.md) to get started. ## License