actions/dependency-review-action
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

editing configuration and remaining sections

Browse Source
This commit is contained in:
Anne-Marie
2024-05-23 10:03:57 +00:00
parent 258a2295c6
commit 9eb0dccbc9
1 changed files with 91 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
README.md
View File

@@ -3,7 +3,7 @@
- [Overview](#overview)
- [Installation](#installation)
- [Configuration](#configuration)
- [Using dependency review action to block a pull request from being merged](#using-dependency-review-action-to-block-a-pull-request-from-being-merged)
- [Outputs](#outputs)
- [Getting help](#getting-help)
- [Contributing](#contributing)
@@ -83,9 +83,16 @@ You can install the action on repositories on GitHub Enterprise Server.
```
5. In the workflow file, replace the `runs-on` value with the label of any of your runners. (The default value is `self-hosted`.)
## Configuration options
## Configuration
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](#configuration-options)
- [Configuration methods](#configuration-methods)
### Configuration options
There are various configuration options you can use to customize the dependency review action.
All configuration options are optional.
| Option | Usage | Possible values | Default value |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------- |
@@ -107,81 +114,106 @@ Configure this action by either inlining these options in your workflow file, or
| `show-openssf-scorecard-levels` | When set to `true`, the action will output information about all the known OpenSSF Scorecard scores for the dependencies changed in this pull request. | `true`, `false` | `true` |
| `warn-on-openssf-scorecard-level` | When `show-openssf-scorecard-levels` is set to `true`, this option lets you configure the threshold for when a score is considered too low and gets a :warning: warning in the CI. | Any positive integer | 3 |
\*not supported for use with GitHub Enterprise Server
> [!NOTE]
> - \* Not supported for use with GitHub Enterprise Server. (Checking for licenses is not supported on GitHub Enterprise Server because the API does not return license information.)
> - \+ When `warn-only` is set to `true`, all vulnerabilities, independently of the severity, will be reported as warnings and the action will not fail.
> - The `allow-licenses` and `deny-licenses` options are mutually exclusive; 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**.
+when `warn-only` is set to `true`, all vulnerabilities, independently of the severity, will be reported as warnings and the action will not fail.
### Configuration methods
### Inline Configuration
To specify settings for the dependency review action, you can choose from two options:
- [Option 1: Inline the configuration options]() in your workflow file.
- [Option 2: Reference an external configuration file]() in your workflow file.
You can pass options to the Dependency Review GitHub Action using your workflow file.
#### Option 1: Using inline configuration
#### Example
You can pass configuration options to the dependency review action using your workflow file.
```yaml
name: 'Dependency Review'
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v4
- name: Dependency Review
uses: actions/dependency-review-action@v4
with:
fail-on-severity: moderate
1. In the same YAML workflow file you created during installation, use the `with:` key to specify your chosen settings:
```yaml
name: 'Dependency Review'
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v4
- name: Dependency Review
uses: actions/dependency-review-action@v4
with:
fail-on-severity: moderate
# Use comma-separated names to pass list arguments:
deny-licenses: LGPL-2.0, BSD-2-Clause
```
# Use comma-separated names to pass list arguments:
deny-licenses: LGPL-2.0, BSD-2-Clause
```
### Configuration File
#### Option 2: Using an external configuration file
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.
You can use an external configuration file to specify settings for this action. The file can be a local file or a file in an external repository.
| 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` <br> **External repo**: `github/octorepo/dependency-review-config.yml@main` |
| `external-repo-token` | Specifies a token for fetching the configuration file. It is required if the file resides in a private external repository and for all GitHub Enterprise Server repositories. Create a token in [developer settings](https://github.com/settings/tokens). | Any token with `read` permissions to the repository hosting the config file. |
1. In the same YAML workflow file you created during installation, use `config-file` to specify that you are using an external configuration file.
#### Example
```yaml
name: 'Dependency Review'
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v4
- name: Dependency Review
uses: actions/dependency-review-action@v4
with:
config-file: './.github/dependency-review-config.yml'
```
| 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` <br> **External repo**: `github/octorepo/dependency-review-config.yml@main` |
2. Optionally, if the file resides in a private external repository, and for all GitHub Enterprise Server repositories, use `external-repo-token` to specify a token for fetching the file.
Start by specifying that you will be using an external configuration file:
```yaml
- name: Dependency Review
uses: actions/dependency-review-action@v4
with:
config-file: 'github/octorepo/dependency-review-config.yml@main'
external-repo-token: 'ghp_123456789abcde'
```
```yaml
- name: Dependency Review
uses: actions/dependency-review-action@v4
with:
config-file: './.github/dependency-review-config.yml'
```
| Option | Usage | Possible values |
|--------------------- | ----------- | ----------------------------- |
| `external-repo-token` | Specifies a token for fetching the configuration file. It is required if the file resides in a private external repository and for all GitHub Enterprise Server repositories. Create a token in [developer settings](https://github.com/settings/tokens). | Any token with `read` permissions to the repository hosting the config file. |
3. Create the configuration file in the path you specified for `config-file`.
4. In the configuration file, specify your chosen settings.
```yaml
fail_on_severity: 'critical'
allow_licenses:
- 'GPL-3.0'
- 'BSD-3-Clause'
- 'MIT'
```
> [!NOTE]
> For external configuration files, the option names use underscores instead of dashes.
> Example: `fail_on_severity`
And then create the file in the path you just specified. Please note
that the **option names in external files use underscores instead of dashes**:
```yaml
fail_on_severity: 'critical'
allow_licenses:
- 'GPL-3.0'
- 'BSD-3-Clause'
- 'MIT'
```
#### Further example configurations
For more examples of how to use this action and its configuration options, see the [examples](docs/examples.md) page.
### Considerations
## Using dependency review action to block a pull request from being merged
- Checking for licenses is not supported on Enterprise Server as the API does not return license information.
- The `allow-licenses` and `deny-licenses` options are mutually exclusive; 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
The Dependency Review GitHub Action check will only block a pull request from being merged if the repository owner has required the check to pass before merging. For more information, see the [documentation on protected branches](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging).
You can configure your repository to block a pull request from being merged if the pull request fails the dependency review action check. To do this, the repository owner must configure branch protection settings that require the check to pass before merging. For more information, see "[Require status checks before merging](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging)" in GitHub Docs documentation.
## Outputs
[Insert overview line here - what does output refer to? What / how it is used?]
- `comment-content` is generated with the same content as would be present in a Dependency Review Action comment.
- `dependency-changes` holds all dependency changes in a JSON format. The following outputs are subsets of `dependency-changes` filtered based on the configuration:
- `vulnerable-changes` holds information about dependency changes with vulnerable dependencies in a JSON format.
@@ -191,7 +223,7 @@ The Dependency Review GitHub Action check will only block a pull request from be
> [!NOTE]
> Action outputs are unicode strings [with a 1MB size limit](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-docker-container-and-javascript-actions).
> [!IMPORTANT]
> [!NOTE]
> If you use these outputs in a run-step, you must store the output data in an environment variable instead of using the output directly. Using an output directly might break shell scripts. For example:
>
> ```yaml