Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the README #324

Merged
merged 7 commits into from Nov 11, 2022
Merged

Update the README #324

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2f59625
reorg the readme
courtneycl Nov 11, 2022
8d7a4c4
Update README.md
courtneycl Nov 11, 2022
89a074e
Update README.md
courtneycl Nov 11, 2022
8e50001
Update README.md
courtneycl Nov 11, 2022
28c7c8c
Set the correct default for license-check in README.
febuiles Nov 11, 2022
a476131
Add `pull_request` to the list of events that don't need refs.
febuiles Nov 11, 2022
9b3a7f6
Minor README tweaks.
febuiles Nov 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
264 changes: 41 additions & 223 deletions README.md
View file
Open in desktop
Expand Up @@ -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:

<img width="854" alt="Screen Shot 2022-03-31 at 1 10 51 PM" src="https://user-images.githubusercontent.com/2161/161042286-b22d7dd3-13cb-458d-8744-ce70ed9bf562.png">

or on the job summary
or on the job summary:

<img src="https://user-images.githubusercontent.com/7847935/182871416-50332bbb-b279-4621-a136-ca72a4314301.png">

Expand All @@ -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
Expand All @@ -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 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_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/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_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/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. | `development`, `runtime`, `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` | `false` |
| `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_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'
Expand All @@ -249,94 +100,61 @@ 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

# Use comma-separated names to pass list arguments:
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 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`, <br> 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'
Comment on lines +136 to +138
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is having quotes right here? In the current README the individual YAML examples don't have quotes 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quotes in YAML are optional, can be taken out if needed!

```

### 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

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/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging).

## 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

Expand Down