Block Noncompliant Dependencies in GitHub PRs

How do I block noncompliant dependencies in GitHub pull requests

Block them at merge time, not by trying to police every contributor. In GitHub, the clean setup is a protected branch or ruleset on the target branch, required dependency and security checks, and a check that fails when a pull request introduces an unapproved dependency change. GitHub documents required status checks, branch protection, rulesets, and dependency review as the pieces that enforce this.

Start with the branch that receives merges, usually main or release/*. Add a ruleset or branch protection rule that requires pull requests before merging and requires status checks to pass before merging. GitHub says required status checks block merges until the named checks succeed, and rulesets can also require code scanning results and other controls.

Then make dependency review part of the pull request. GitHub’s dependency review view shows changes in manifests and lockfiles, and it warns about vulnerable dependencies in the diff. If your policy is about license approval, source approval, or package allowlists, your CI job should read the changed dependency files and fail when the pull request adds something outside policy. GitHub also notes that some dependencies may not appear if they cannot be parsed, so the source diff still needs review.

The part people get wrong is assuming a review comment can block the merge by itself. Comments can be ignored, and even code review approval does not enforce dependency policy unless the branch requires the check that produced the decision. The block needs to live in a required status check or a required code scanning result, because GitHub only stops the merge when the required check fails.

A practical pattern is a dedicated workflow such as dependency-policy that runs on pull requests, inspects the changed package files, and exits nonzero when it sees an unapproved package, version, registry, or license. Mark that workflow as required in the branch ruleset. GitHub allows required status checks to be tied to a specific app or source, which matters when you want only your policy checker to count.

If you already use code scanning, add it to the gate as well. GitHub says code scanning alerts can appear on pull requests, and branch protection or rulesets can require the code scanning results check before merging. That is useful when a dependency change also introduces insecure code paths in your own repository. It does not replace dependency policy, because a clean code scan does not mean the dependency itself is approved.

Use merge protection carefully when you want the check to cover the exact code that will land. GitHub notes that checks from earlier commits do not satisfy required status checks, and if branch protection requires the branch to be up to date, you need the latest base branch before merge. That matters for dependency changes, because a later rebase can bring in a new lockfile or a new transitive package set.

The inconvenient part is lockfiles. A pull request can look harmless in package.json, poetry.lock, Cargo.lock, or Gemfile.lock, then silently change the actual resolved graph. Treat the lockfile as part of policy, not as noise. If the lockfile changes and the new graph contains a disallowed package or version, fail the check even when the direct dependency name itself stayed the same. GitHub’s dependency review guidance specifically points people back to manifest and lockfile diffs.

For stronger control, split policy into two checks. One check answers, “Did this pull request change dependencies?” The second answers, “Are those changes allowed?” The first can be lightweight and the second can enforce a allowlist, a license policy, or a minimum review rule for package sources. GitHub’s status-check ruleset model supports this well, because each check can become a merge requirement.

Watch for ambiguous check names. GitHub warns that using the same job name in multiple workflows can cause ambiguous status check results and block pull requests from being merged. If you create a dependency policy workflow, give it a unique job name and keep that name stable so the required check always maps to the same source.

If you need a simple implementation path, use this sequence: create a policy workflow, have it inspect dependency files, fail on disallowed packages or licenses, require that workflow in the target branch ruleset, then add dependency review and code scanning if you already use them. That gives you a hard stop at merge time instead of a soft warning in comments. GitHub’s docs support each step as a native control.

If your repository uses GitHub Actions for the required checks, make sure the workflow also handles merge-queue behavior where relevant. GitHub’s troubleshooting docs call out that required checks can hang or fail to report if the workflow is not wired for the events GitHub uses during merge protection. A blocked pull request that waits forever is not policy, it is a broken gate.

The end state is simple: contributors can open pull requests, but they cannot merge dependency changes unless the branch ruleset or protection rule sees a passing policy check. That is the right place to block noncompliant dependencies, because it is enforced, visible, and tied to the exact code that would ship.

FAQ

Can GitHub block a pull request just from dependency review No. Dependency review shows and warns about dependency changes, but merge blocking comes from branch protection or rulesets that require a status check or similar gate to pass.

Should I block on only direct dependencies, or transitive ones too Block both when your policy cares about the final resolved graph. Direct dependencies are visible in the manifest, but lockfiles and package manager resolution can introduce transitive packages that matter just as much. GitHub’s dependency review guidance points to manifest and lockfile diffs, which is the right place to inspect the resolved set.

What happens if a required check name changes or is duplicated GitHub can treat that as an ambiguous or missing required check, which blocks the pull request from merging. Keep the workflow and job name stable, and use one clear source for the policy result.

Do code scanning rules replace dependency policy No. Code scanning is useful for security findings in your code, and GitHub can require its results before merge, but it does not replace a dependency allowlist, license policy, or registry policy.

Where should the policy live if I want it to be hard to bypass Put the control on the protected target branch or ruleset, not in contributor instructions. GitHub lets you require pull requests, require status checks, and restrict bypasses, which is what makes the block real.