Starting with the plain-language idea before touching any technical detail.

Almost every modern application depends on external packages — libraries someone else wrote, published to a registry like npm, PyPI, RubyGems, or Maven, and pulled into a project through a manifest file such as package.json or requirements.txt. Over the life of a project, those dependencies get added, upgraded, downgraded, and removed constantly, often inside pull requests that also contain unrelated application code.

The Dependency Review API is a GitHub REST API endpoint that compares the full set of dependencies between two points in a repository’s history — typically the base branch and the head of a pull request — and returns a structured “diff” of exactly what changed, along with any known security vulnerabilities and license information for those dependencies.

It is closely related to, but distinct from, the dependency review feature you might already see as a visual diff on the “Files changed” tab of a pull request in the GitHub web interface. The visual feature is what a human sees; the API is the underlying data source that powers it — and that other tools, scripts, and automated checks can call directly.

The supply-chain security problem this API is built to address.

A typical application might declare a few dozen direct dependencies in its manifest, but pull in hundreds more indirectly — dependencies of dependencies, several layers deep. Very few developers manually audit that entire tree on every pull request; it simply isn’t practical by hand. Attackers have learned to exploit exactly this gap, publishing malicious versions of popular packages, or waiting for known vulnerabilities in older versions to be reused by projects that never got around to upgrading.

The Dependency Review API turns an invisible, easy-to-skip step — “did this pull request just add something risky?” — into a structured, machine-readable answer that can be checked automatically, every single time, without relying on a human reviewer noticing a one-line change buried in a long lock file diff.

The Dependency Review API doesn’t work alone — it sits on top of, and alongside, several related pieces.

GitHub’s supply-chain security tooling is built in layers, and understanding the layering prevents a lot of confusion about which piece does what.

flowchart TD
    A[Manifest & Lock Files in Repo] --> B[Dependency Graph]
    S[Dependency Submission API] --> B
    B --> C[Dependency Review API]
    C --> D[Dependency Review Action]
    C --> E[Files Changed Tab in PR UI]
    D --> F{Severity Above Threshold?}
    F -- Yes --> G[PR Check Fails]
    F -- No --> H[PR Check Passes]
        

What you actually ask for, and what comes back, described conceptually.

A request to the Dependency Review API is aimed at a specific repository and asks it to compare two references — a base and a head, written together as a single comparison range. Those references can be branch names, tags, or commit identifiers; the API works out the dependency state at each point and produces the difference between them.

Tracing the sequence from an opened pull request to a finished check.

When a contributor opens a pull request that changes a manifest or lock file, a chain of events can be set in motion, most commonly through the dependency review action running as part of a GitHub Actions workflow.

sequenceDiagram
    participant C as Contributor
    participant P as Pull Request
    participant W as Actions Workflow
    participant D as Dependency Review API
    participant G as Dependency Graph

    C->>P: Open PR changing package.json
    P->>W: Triggers dependency review workflow
    W->>D: Request comparison (base...head)
    D->>G: Read dependency state at base
    D->>G: Read dependency state at head
    G-->>D: Dependency lists for both points
    D->>D: Compute diff + attach vulnerability/license data
    D-->>W: Structured comparison result
    W->>W: Apply configured thresholds (severity, licenses)
    alt Above threshold or disallowed license found
        W-->>P: Check fails, details shown in PR
    else Nothing concerning found
        W-->>P: Check passes
    end
        

Notice that the API itself doesn’t decide pass or fail — it only reports facts: what changed, and what’s known about it. The decision of what counts as “too risky” (which severity level, which licenses are disallowed) is configured separately, in the action or in whatever tool is calling the API. This separation keeps the underlying data reusable for many different policies.

Zooming out from a single request to how this data stays current over time.

One subtlety worth understanding: because advisories are published continuously, a dependency that looked clean when a pull request was first opened can later be flagged if a new vulnerability is disclosed for it. Re-running the check, rather than relying on a result from days earlier, keeps the information current.

You may likeWhat Is Git LFS (Large File Storage)?→

Availability differs between public and private repositories, which trips up teams moving code between the two.

This split is intentional: GitHub treats supply-chain visibility for open-source, publicly visible code as a broadly available safety feature, while treating it as part of the more advanced, licensed security suite once private, proprietary code is involved.

Two different ways to consume the same underlying data, suited to different needs.

Most teams start with the ready-made action, since it covers the most common need — failing a pull request when a newly introduced dependency is too risky — without writing any integration code. Teams with more specific requirements, such as routing results into an existing compliance system, tend to graduate to calling the API directly, often from within their own Actions workflow.

A detail that matters specifically for ecosystems that rely on the separate Dependency Submission API.

Some ecosystems can’t be fully understood just by reading a manifest file — a compiled language’s actual dependency tree might only be knowable after a build step runs. For these cases, GitHub offers the Dependency Submission API, letting build tooling submit the resolved dependency list directly, which then feeds into the same dependency graph the review API reads from.

The safer pattern is to keep both steps inside the same GitHub Actions workflow, in a defined order, so the review action always runs after the submission step has finished — giving up direct control over exact timing in exchange for a guarantee that the comparison sees complete, current data.

Weighing what this feature genuinely improves against its real limitations.

How this feature fits into a broader supply-chain security strategy, and what it doesn’t cover.

Dependency review is one part of a larger picture that typically also includes secret scanning, code scanning, and Dependabot alerts and updates. Together, these cover different stages: dependency review catches risky changes at the pull request stage, before merge; Dependabot alerts continue watching already-merged dependencies for newly disclosed vulnerabilities over time; code scanning looks at the project’s own source code rather than its dependencies.

Making sure the signal this feature produces actually gets seen and acted on.

Results from the dependency review action appear directly on the pull request as a check, along with a detailed breakdown on the “Files changed” tab, making them visible in the same place a reviewer already looks. Teams calling the API directly are responsible for deciding how results surface — a common pattern is posting a summary comment on the pull request, or sending a notification to a security channel when severity crosses a defined threshold.

Because advisory data changes over time, a periodic, project-wide review of currently allowed licenses and severity thresholds — not just per-pull-request checks — helps catch policy drift as an organization’s risk tolerance or compliance requirements evolve.

Approaches that work well in practice, and traps worth avoiding.

A condensed checklist drawn from everything discussed so far.

Concrete situations where these ideas show up in everyday engineering work.

No, not by itself. It returns structured comparison data; deciding what counts as “too risky” and failing a check accordingly is handled separately, typically by the dependency review action’s configuration.

Private repository usage requires an organization on GitHub Enterprise Cloud with a GitHub Advanced Security license. It’s available on all public repositories regardless of plan.

The visual diff in the pull request UI is a human-facing presentation of dependency changes; the API is the underlying data source, callable directly for custom tooling and automation.

No. It relies on published advisory data. A vulnerability that hasn’t been disclosed or added to the advisory database yet won’t be flagged until it is.

Not always. Many ecosystems are fully understood just from manifest and lock files. Submission becomes important for ecosystems where the true dependency tree is only resolvable at build time.

Yes. Alongside vulnerability data, results include license information, and the dependency review action supports configuring allowed and disallowed license lists.

It compares the base branch the pull request targets against the head of the pull request branch, reflecting exactly what that pull request would change if merged.

The Dependency Review API gives GitHub a structured, automatable way to answer a question every pull request implicitly raises: what open-source packages would this change actually introduce, and is any of it known to be risky? By comparing a base and head reference against GitHub’s dependency graph and attaching vulnerability and license data to the result, it turns a step that’s easy to skip by hand into a consistent, repeatable check — whether consumed through the ready-made dependency review action or called directly for custom tooling.