Set Up GitHub License Compliance Checks on PRs

How do I set up license compliance checks so pull requests block noncompliant dependencies on GitHub

Use GitHub’s dependency review for pull requests, define the licenses you allow, then require that check in branch protection or a ruleset. When the check fails, the pull request stays unmergeable until the offending dependency is removed or approved. GitHub documents dependency review as the place where license information is surfaced on dependency changes, and its license compliance feature is designed to enforce policy across pull requests.

Start with the repository side, because the enforcement point lives there. GitHub says dependency review is available for public repositories and for private repositories with GitHub Code Security or GitHub Advanced Security enabled. The review action can compare dependency changes in a pull request and report invalid licenses, so that is the control you wire into CI first.

Add the dependency review action to your pull request workflow. GitHub’s documentation shows the action configured in GitHub Actions, and the config file can list SPDX-compliant license identifiers or expressions. That is the part people get wrong: they skip the workflow and try to enforce licensing only in policy text, but nothing blocks a merge unless a status check actually runs on the pull request.

A minimal workflow looks like this:

```yaml name: dependency-review on: pull_request: branches: [main]

jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: read steps: - name: Dependency Review uses: actions/dependency-review-action@v4 with: config-file:.github/dependency-review-config.yml ```

GitHub’s docs show the same pattern, and the exact action version can change over time, so pin the version you use and update it intentionally. The important part is that the workflow runs on pull_request, not only on push, because merge blocking has to happen before code lands on the protected branch.

Create the license policy file next. GitHub supports SPDX license identifiers and expressions in the dependency review configuration, which is where you define acceptable and unacceptable licenses for new dependencies introduced by a pull request. Keep the policy narrow enough to match your legal review, because a broad allow list is easier to maintain than a vague exception process.

A practical config file can start simple:

yaml license-check: deny: - GPL-3.0-only - AGPL-3.0-only - LGPL-3.0-only allow: - MIT - Apache-2.0 - BSD-3-Clause

Use the exact license identifiers your team has approved, and keep the file in the repository so changes to policy are reviewed like code. The inconvenient part is that the first version will not be perfect, because some packages ship dual licenses, some transitive dependencies carry different terms, and some ecosystems report license metadata inconsistently. GitHub’s license compliance pages are built around reviewing new dependency introductions, not pretending every license question is simple.

Protect the default branch with a required check. GitHub’s docs and marketplace listing both point to required status checks before merging, which is the gate that turns a scan into an actual block. Add the dependency review job to the required checks list, and make sure the rule applies to the branch your pull requests merge into, usually main or trunk.

If your organization uses rulesets, require the dependency compliance result there instead of relying on a loose branch rule. GitHub’s recent license compliance feature is built around a ruleset condition called “Require license compliance check results before merging,” which is the cleanest way to make a license failure stop the merge. That is the enforcement layer you want when multiple repositories need the same policy.

Test the whole path with a dependency that you know violates policy. Open a pull request that adds or upgrades a package with a denied license, then confirm the status check fails and the merge button is blocked. If the check passes when it should fail, the usual causes are wrong workflow trigger, missing permissions, policy file path mismatch, or the branch rule not requiring the check.

Handle exceptions through the policy, not through side channels. GitHub’s license compliance flow lets reviewers assess a dependency and approve or reject it through the compliance process, which keeps decisions auditable. If you need an exception for a specific package, record that in the policy or the reviewer workflow, then require a fresh check so the merge gate reflects the current decision.

Watch the edge cases that usually surprise teams. Dependency review only sees what is introduced in the pull request, so a branch can still contain old noncompliant dependencies until they are touched by a change. Internal packages, private registries, and nested transitive dependencies can also produce license metadata that needs review before you call the system done. GitHub’s own guidance frames dependency review as a diff-based control, which is why baseline cleanup matters.

A good rollout path is repository by repository. Enable the workflow, add the policy file, require the check, then fix the failures that come back from real pull requests. After that, copy the pattern into your organization template so new repositories start with the control already in place. If you already use DevConnect for testing and release coordination, keep that workflow separate, because license compliance belongs on the repo that owns the code.

For a smaller team, one maintainer can own the initial license list and the exception review. For a larger org, GitHub’s enterprise license compliance feature is built for centralized policy enforcement, with compliance reviewers handling requests from developers who hit a blocked dependency. That central review path matters because it keeps the legal decision separate from the merge decision.

If you want the shortest working version, the sequence is this: enable dependency review, define allowed and denied licenses, run it on pull requests, and require the resulting status check before merge. Once that is in place, a noncompliant dependency does not rely on memory, code review discipline, or a manual reminder. The pull request itself carries the block.