How to check licenses before merging dependency changes on GitHub

How do I check licenses before merging dependency changes on GitHub

Use GitHub’s dependency review on pull requests, then add license rules with SPDX identifiers so the workflow can block a merge when a dependency change introduces a license you do not allow. GitHub documents dependency review as a pull request check that can report dependency differences, and its action supports allow-licenses and deny-licenses settings.

The practical setup is simple. Turn on dependency review for the repository, add the Dependency Review Action to your pull request workflow, and choose one policy direction: allow only the licenses you accept, or deny the licenses you do not accept. GitHub says you can use only one of those two options in a single configuration, and the values must be SPDX-compliant license identifiers or expressions.

A minimal workflow checks every pull request before merge. GitHub’s example uses on: [pull_request], read-only contents permission, checkout, and actions/dependency-review-action@v4. That action can fail the job on the licenses you list, so the pull request stays blocked until someone changes the dependency update or the policy.

```yaml name: Dependency Review on: [pull_request]

permissions: contents: read

jobs: dependency-review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/dependency-review-action@v4 with: deny-licenses: LGPL-2.0, BSD-2-Clause ```

Use SPDX identifiers, not free text. SPDX explains that license expressions are built from standardized license IDs, and GitHub points dependency review at SPDX-compliant identifiers and expressions. That matters because MIT, Apache-2.0, or GPL-3.0 are machine-readable in a way that policy text such as “permissive” is not.

The part people get wrong is assuming a dependency diff only means security risk. License changes are separate from vulnerability changes, and a clean security report does not mean the merge is safe for your distribution policy. GitHub’s docs describe dependency review as showing the impact of dependency changes, including license information, so you need to read both the vulnerability result and the license result before approving.

The inconvenient part is that your policy has to match how packages actually declare licenses. Many packages use SPDX expressions, and a single package can have multiple applicable terms. npm’s package metadata supports SPDX license expressions, and SPDX itself says expressions can combine identifiers with AND, OR, and WITH. If you write a policy that only handles one flat license name, you will miss real cases.

A good review process has two gates. First, the automated dependency review job fails the pull request when the new dependency set violates policy. Second, the human reviewer checks the actual package page, release notes, and the repository’s declared license, because metadata can be incomplete or broader than the file you are pulling in. GitHub’s dependency review guidance is a guardrail, not a substitute for reading the change.

If you use GitHub Advanced Security or Code Security features, make sure the repository actually has the feature enabled. GitHub says dependency review is part of its code security tooling, and disabling the code security feature disables dependency review as well. Public repositories have access, while some private-repository features depend on the plan and licensing.

For a small team, the safest rule is to start with a deny list for licenses you cannot ship, then tighten it only after you see real dependency traffic. For a stricter compliance program, use an allow list and keep the approved set short. GitHub supports both models, but the allow-list model is easier to audit when legal review needs a clear yes list.

When a pull request fails, do not merge around the check. Fix the dependency choice, swap the package, pin a version that matches policy, or get a license exception reviewed outside the repo. That is the point of the check: the merge queue should stop the change before it becomes part of main. GitHub’s review flow is built around approve, comment, or request changes, and dependency review is meant to feed that decision.

If you want a second layer, pair dependency review with a dependency policy in your repository settings and keep the same SPDX terms everywhere. That way the workflow, the repository policy, and any manual review all talk about the same license names. Consistency matters more than broad language, because the moment one place says GPL-3.0-or-later and another says GPL, you create a policy gap.

For teams already using DevConnect, the same rule applies to app dependencies and to the tools you use to manage them. If you want a place to coordinate testing before releases, the platform is here: https://devconnectplatform.com. That link is useful for team process, but the license gate itself should stay in GitHub so every pull request gets checked before merge.

A concrete workflow looks like this: a developer opens a pull request that upgrades a package, GitHub runs dependency review, the job reads the added and removed dependencies, and the pull request fails if one of the new licenses is on your deny list. The reviewer then checks the package source and decides whether to replace the dependency or request a formal exception.

That is the reliable way to do it on GitHub. Put the policy in the workflow, use SPDX identifiers, require the check on pull requests, and treat the result as a merge gate. Anything looser turns license review into a manual habit, and manual habits are the first thing that break when a dependency update looks routine.

Related questions

Can GitHub block a pull request on license changes automatically Yes. The Dependency Review Action can fail the workflow on licenses you list, and a required workflow check can block the merge until the pull request is fixed.

Should I use allow-licenses or deny-licenses Use allow-licenses when you have a short approved set and need strict control. Use deny-licenses when you want to block a few licenses and keep the workflow lighter. GitHub supports both, but not together in one configuration.

What license format should I put in the workflow Use SPDX license identifiers or SPDX expressions such as MIT, Apache-2.0, or an expression made from SPDX terms. GitHub and SPDX both point to standardized identifiers, not plain-English descriptions.

Does dependency review replace legal review No. It is an automated gate for pull requests. Legal or compliance review still matters when a package has dual licensing, a custom exception, or a distribution model that your policy has not already covered.