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

PR with suggestions - [Improvement]: Help streamline / simplify dependency review action README #773

Merged
merged 12 commits into from
May 30, 2024
Merged

PR with suggestions - [Improvement]: Help streamline / simplify dependency review action README #773

Changes from 9 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
4c0a483
Update README.md
am-stead May 23, 2024
258a229
installation section
am-stead May 23, 2024
9eb0dcc
editing configuration and remaining sections
am-stead May 23, 2024
f38966f
updating overview
am-stead May 23, 2024
d3670a3
updating GHES links
am-stead May 23, 2024
d5b8317
edits
am-stead May 24, 2024
9770b8d
Update README.md
am-stead May 27, 2024
2d3c93c
Update README.md
am-stead May 27, 2024
3fe3159
Indenting to match `vulnerable-changes`
am-stead May 27, 2024
5751523
Update README.md
jonjanego May 29, 2024
c601a5a
combining Output notes
am-stead May 30, 2024
87b53ae
add line break
am-stead May 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
311 changes: 185 additions & 126 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,70 +1,103 @@
# dependency-review-action

This action scans your pull requests for dependency changes, and will
raise an error if any vulnerabilities or invalid licenses are being introduced. The action is supported by an [API endpoint](https://docs.github.com/rest/dependency-graph/dependency-review) that diffs the dependencies between any two revisions on your default branch.
- [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)
- [License](#license)

The action is available for all public repositories, as well as private repositories that have GitHub Advanced Security licensed.
## Overview

You can see the results on the job logs:
The dependency review action scans your pull requests for dependency changes, and will raise an error if any vulnerabilities or invalid licenses are being introduced.
The action is supported by an [API endpoint](https://docs.github.com/en/rest/dependency-graph/dependency-review?apiVersion=2022-11-28) that diffs the dependencies between any two revisions on your default branch.

<img width="850" alt="GitHub workflow run log showing Dependency Review job output" src="https://user-images.githubusercontent.com/2161/161042286-b22d7dd3-13cb-458d-8744-ce70ed9bf562.png">
The action is available for:
- Public repositories
- Private repositories with a [GitHub Advanced Security](https://docs.github.com/en/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security) license.

or on the job summary:
### Viewing the results

<img width="850" alt="GitHub job summary showing Dependency Review output" src="https://github.com/actions/dependency-review-action/assets/2161/42fbed1d-64a7-42bf-9b05-c416bc67493f">
When the action runs, you can see the results on:

- The **job logs** page.
1. Go to the **Actions** tab for the repository and select the relevant workflow run.
1. Then under "Jobs", click **dependency review**.

<img width="850" alt="GitHub workflow run log showing Dependency Review job output" src="https://user-images.githubusercontent.com/2161/161042286-b22d7dd3-13cb-458d-8744-ce70ed9bf562.png">

- The **job summary** page.
1. Go to the **Actions** tab for the repository and select the relevant workflow run.
1. Click **Summary**, then scroll to "dependency-review summary".

<img width="850" alt="GitHub job summary showing Dependency Review output" src="https://github.com/actions/dependency-review-action/assets/2161/42fbed1d-64a7-42bf-9b05-c416bc67493f">

## Installation

**Please keep in mind that you need a [GitHub Advanced Security](https://docs.github.com/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security) license if you're running this action on private repositories.**
- [Installation (standard)](#installation)
- [Installation (GitHub Enterprise Server)](#installation-github-enterprise-server)

#### Installation (standard)

You can install the action on any public repository, or any organization-owned private repository, provided the organization has a GitHub Advanced Security license.

1. Add a new YAML workflow to your `.github/workflows` folder:

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

### GitHub Enterprise Server

Make sure
[GitHub Advanced
Security](https://docs.github.com/enterprise-server@3.8/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise)
and [GitHub
Connect](https://docs.github.com/enterprise-server@3.8/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)
are enabled, and that you have installed the [dependency-review-action](https://github.com/actions/dependency-review-action) on the server.

You can use the same workflow as above, replacing the `runs-on` value
with the label of any of your runners (the default label
is `self-hosted`):

```yaml
# ...

jobs:
dependency-review:
runs-on: self-hosted
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v4
- name: 'Dependency Review'
uses: actions/dependency-review-action@v4
```

## Configuration options

Configure this action by either inlining these options in your workflow file, or by using an external configuration file. All configuration options are optional.
```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
```

#### Installation (GitHub Enterprise Server)

You can install the action on repositories on GitHub Enterprise Server.

1. Ensure [GitHub Advanced Security](https://docs.github.com/en/enterprise-server@latest/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise) and [GitHub Connect](https://docs.github.com/en/enterprise-server@latest/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect) are enabled for the enterprise.
2. Ensure you have installed the [dependency-review-action](https://github.com/actions/dependency-review-action) on the server.
3. Add a new YAML workflow to your `.github/workflows` folder:

``` 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@v4
```
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

- [Configuration options](#configuration-options)
- [Configuration methods](#configuration-methods)

### Configuration options

There are various configuration options you can use to specify settings for the dependency review action.

All configuration options are optional.

| Option | Usage | Possible values | Default value |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------- |
Expand All @@ -86,91 +119,117 @@ 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

+when `warn-only` is set to `true`, all vulnerabilities, independently of the severity, will be reported as warnings and the action will not fail.

### Inline Configuration

You can pass options to the Dependency Review GitHub Action using your workflow 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:
fail-on-severity: moderate

# Use comma-separated names to pass list arguments:
deny-licenses: LGPL-2.0, BSD-2-Clause
```

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

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

#### Example

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/dependency-review-config.yml'
```

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'
```

For more examples of how to use this action and its configuration options, see the [examples](docs/examples.md) page.
> [!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**.
jonjanego marked this conversation as resolved.
Show resolved Hide resolved

### Configuration methods

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.

#### Option 1: Using inline configuration

You can pass configuration options to the dependency review action using your workflow file.

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

#### Option 2: Using an external configuration file

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.

1. In the same YAML workflow file you created during installation, use `config-file` to specify that you are using an external configuration 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:
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.

```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'
```

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

### Considerations
#### Further information

- 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**.
- For more examples of how to use this action and its configuration options, see the [examples](docs/examples.md) page.
- For general information about dependency review on GitHub, see "[About dependency review](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)" in the GitHub Docs documentation.

## Blocking pull requests
## Using dependency review action to block a pull request from being merged

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

Dependency review action can create [outputs](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs), so that data from its execution can be used by other jobs in a workflow.

- `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.
- `invalid-license-changes` holds information about invalid or non-compliant license dependency changes in a JSON format.
- `denied-changes` holds information about denied dependency changes in a JSON format.
- `vulnerable-changes` holds information about dependency changes with vulnerable dependencies in a JSON format.
- `invalid-license-changes` holds information about invalid or non-compliant license dependency changes in a JSON format.
- `denied-changes` holds information about denied dependency changes in a JSON format.

> [!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]
jonjanego marked this conversation as resolved.
Show resolved Hide resolved
> 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
Expand Down