Adding a package can change more than one line in a manifest. A lockfile may bring in a vulnerable transitive dependency, or a package may have a license your project cannot use. GitHub Dependency Review helps you inspect these changes in a pull request before they reach your default branch.
The GitHub dependency review view shows dependency changes; the Dependency Review Action adds a GitHub Actions check that can fail a pull request when configured conditions are met. This guide covers that action for an individual maintainer or small team. It is a check on dependency changes, not a complete security audit of your code or every dependency already in the repository.
What Dependency Review checks
When a pull request changes supported package manifests or lockfiles, GitHub can show which dependencies were added, removed, or updated. The review can include indirect dependencies from lockfiles, release dates, dependency information, and known vulnerability data. The Dependency Review overview explains the built-in review and the separate action.
The action compares dependency snapshots for the pull request's base and head commits through GitHub's dependency review API. It can fail a workflow for vulnerabilities that the change introduces, and it can check license data. This is useful for a new package or a version update; use Dependabot alerts as well to find known vulnerabilities in dependencies already present on the default branch.
Coverage depends on the dependency graph. GitHub supports specific ecosystems and file formats, so check the current supported package ecosystems. Commit your lockfile when your package manager uses one: it helps make the resolved versions, including transitive packages, visible for review. A dynamically assembled dependency list or an unsupported ecosystem may need the dependency submission API rather than relying only on manifest parsing.
Check access and prerequisites first
- Enable the repository's dependency graph. GitHub parses supported manifest and lock files and updates the graph as the repository changes. Enabling it gives GitHub read-only access to those files.
- Make sure GitHub Actions is enabled and the repository can use Dependency Review. It is available for public repositories; private-repository eligibility depends on the GitHub Code Security or Advanced Security entitlement for the account.
- Keep the dependency files that describe the built application current. A stale lockfile can make the graph a poor representation of what you actually install.
The dependency graph setup guide explains the setting. If the repository is private, confirm the current plan requirements before building the workflow around this feature.
Add a pull-request check
Create .github/workflows/dependency-review.yml:
name: Dependency review
on:
pull_request:
permissions:
contents: read
jobs:
dependency-review:
name: dependency-review
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v6
- name: Review dependency changes
uses: actions/dependency-review-action@v5
with:
fail-on-severity: moderate
This example uses a moderate severity threshold to avoid treating every low-severity finding as a merge blocker. It is a starting point, not a universal policy: the action supports low, moderate, high, and critical, and the selected threshold should reflect the risk your project can accept. The current action documentation lists its options and notes that v5 requires Actions Runner version 2.327.1 or later; check this if you use an older self-hosted runner.
The workflow requests only read access to repository contents. Keep permissions narrow, and do not add secrets or write access for a dependency check that does not need them. GitHub's secure-use guidance for Actions recommends granting the GITHUB_TOKEN only the permissions a workflow requires. For a production workflow, consider pinning third-party actions to a full commit SHA and updating that pin through your normal dependency-update process; the version tag above keeps the example readable.
Decide when a finding should fail
Severity is only one part of a useful policy. The action also supports scope settings for runtime, development, and unknown dependencies. A small service may choose to block runtime findings first, then decide whether vulnerabilities in build and test dependencies should also fail the check. Those dependencies can still matter because they run in development or CI; excluding a scope should be a conscious choice, not an assumption that it is harmless.
The action can also evaluate license information. Treat that as a screening aid, not legal advice: confirm the package's actual license and obligations before accepting or blocking it. Avoid a strict allow-list until someone has reviewed and can maintain the approved list. The action repository marks deny-licenses as deprecated, so check its current configuration documentation before adopting older examples that use it.
Once the check produces results you understand, make it a required status check in your branch protection rule or ruleset. A failed workflow does not by itself prevent a merge if the repository does not require that check. GitHub explains this distinction in its guide to protected branches and required status checks.
For a small team, roll it out on one repository first. Review a few real dependency pull requests, tune the threshold and scope, then require the check for the branches that need protection. Standard GitHub-hosted runners are free for public repositories; private repositories use plan-based minutes and may incur charges after included usage. The GitHub Actions billing guide describes the current billing model.
Triage a flagged dependency change
Do not dismiss a finding just because it is transitive or the pull request was generated by an update bot. Use the pull request's dependency diff and the advisory details to answer:
- Which exact package and version changed, and which direct dependency brought it in?
- Is that version in the advisory's affected range? Is a fixed version available?
- Does the finding apply to a runtime dependency, a development tool, or a scope reported as unknown?
- Can you update, replace, or remove the package without breaking the project?
If a finding is not applicable or cannot be fixed immediately, record the evidence, the reason for accepting the risk, and who will revisit it. The action's allow-ghsas option can exempt a GitHub Advisory Database ID from this check, but an exemption does not remove the dependency or make an underlying security alert disappear. Keep exceptions specific and reviewed rather than adding broad exclusions to make the workflow green.
For license concerns, verify the license against the package's published source and the terms relevant to your distribution. Missing or unexpected license information is a reason to investigate, not proof that the package is safe to ship.
What this check does not replace
Dependency Review only knows what GitHub's dependency data and advisory sources can identify. A clean check does not prove that a package is maintained, that its code is safe, or that your application uses it securely. Newly disclosed vulnerabilities can also appear after a pull request has merged. Keep lockfiles current, review alerts on the default branch, and investigate dependency changes as part of the code review.
This check fits into a focused pull-request process: see our guide to practical Git and GitHub workflows for small projects. If you want update pull requests to arrive automatically, the guide to using Mend Renovate with GitHub Actions covers that complementary workflow.
