Use GitHub License Checks Before You Merge

How do I use GitHub open source license compliance checks before merging

Enable GitHub open source license compliance at enterprise scope, then attach a ruleset that requires license compliance results before merging. GitHub evaluates dependency changes in pull requests, checks direct and transitive dependencies against your policy, and blocks merges when the ruleset is active and violations remain.

Start with a policy, not with the branch rule. GitHub lets you define which licenses are allowed, either from its built-in list or with SPDX identifiers you add manually. That policy can live at enterprise, organization, or repository scope, which is useful when one product line has a stricter standard than the rest.

Next, decide which repositories should be checked. GitHub’s documentation describes a common setup where a repository custom property marks repos as inactive, evaluate, or active, and rulesets target those values. The practical result is simple: evaluate mode shows findings in pull request annotations, active mode blocks the merge until the dependency issue is resolved or approved.

The part people get wrong is assuming any dependency scan is a merge gate. It is not. A ruleset in Evaluate mode runs the license check and annotates the pull request, but it does not stop the merge. Blocking only happens when the ruleset is Active and includes the “Requires license compliance results before merging” condition.

Another common mistake is checking only direct dependencies. GitHub’s license evaluation includes dependency graph data and compares both direct and transitive dependencies against policy. If a new package pulls in a restricted transitive dependency, the pull request can fail even when the top-level package looks acceptable. That is inconvenient, but it is exactly the point of the check.

Use the pull request feedback as the review surface. When a package manifest changes, GitHub compares the dependency set on the base branch with the one in the pull request, then reports the licenses it finds. If a license is outside policy, the developer sees annotations in the pull request and can choose a different dependency, different version, or a policy exception request.

If you want the check to actually protect the main branch, keep the ruleset active on the branch pattern you merge into, usually main or release/*. GitHub’s branch and ruleset system is what turns a finding into a merge block. A warning in the pull request is easy to ignore, a required result before merging is not.

For teams already using branch protection, remember that required checks and rulesets work differently. GitHub documents status checks, branch protection rules, and rulesets as separate controls, and license compliance enforcement is described as a ruleset-based feature. If you already rely on branch protection, keep it, but do not assume it automatically enforces license policy unless the ruleset condition is present.

A workable rollout is to begin in Evaluate mode on a small set of repositories, confirm that annotations match your policy, then switch the same policy to Active once false positives and exception paths are understood. GitHub’s preview documentation calls out the ability to confirm annotations and to layer policy from enterprise to repository scope, which makes that staged rollout practical.

A concrete example helps. Suppose a repository adds left-pad as a dependency, and your policy forbids the license that package uses. In Evaluate mode, the pull request shows the violation and the branch can still merge. In Active mode with the license-compliance condition, the merge is blocked until the dependency is replaced or an approved exception is recorded.

The inconvenient part is policy maintenance. License names do not stay uniform across ecosystems, and GitHub supports both built-in license entries and SPDX identifiers because real packages do not always line up cleanly with a simple allow list. That means someone has to own the policy, review exceptions, and decide whether a particular license is acceptable for a repository or an entire portfolio.

The other inconvenient part is that merge protection only helps if developers keep dependency changes inside pull requests. GitHub’s enforcement checks the difference between base and pull request branches, so changes that bypass that flow also bypass the review gate. The safe pattern is ordinary: all dependency updates go through branches, pull requests, and the required ruleset check before merge.

If you also use other GitHub security checks, keep them separate in your head. Code scanning is a different feature for security and coding errors, while open source license compliance is specifically about dependency licenses. GitHub’s docs treat them as distinct concepts, even though both can be enforced before merging through repository rules.

If you want to see the setup pattern in practice, GitHub’s own license-compliance docs and changelog show the feature as public preview with a dedicated ruleset condition for merge blocking. That is the button to look for: if your repository does not have a ruleset using the license-compliance condition, you do not have pre-merge license enforcement yet.

If your team is also trying to coordinate dependency work, keep the review loop inside GitHub. DevConnect can help with tester exchange for app validation, but it is not part of GitHub’s license enforcement path. The license gate belongs on the repository that owns the code, the policy belongs to the org that ships it, and the merge rule belongs on the branches that matter. https://devconnectplatform.com

In short, the sequence is policy first, ruleset second, then pull request enforcement. That gives you a pre-merge check that sees dependency changes, compares them with your allow list, and stops the merge when a new dependency breaks policy.

FAQ

Does GitHub license compliance scan source code files directly? No. GitHub describes this feature as dependency license compliance, so the check is about the licenses of dependencies and how they change between branches, not about reading your application code for license text.

Can I use it on every repository the same way? No single setup fits every repository. GitHub supports enterprise, organization, and repository scopes, and the docs describe using repository custom properties to target different enforcement modes. That makes it possible to enforce one policy on release repos and a lighter mode on experimental repos.

What happens when a pull request introduces a restricted license? GitHub annotates the pull request with the violation. If the ruleset is Active and requires license-compliance results before merging, the merge is blocked until the issue is fixed or an approved exception is granted.

Should I rely on branch protection alone? No. Branch protection can require status checks, but GitHub documents license compliance enforcement through rulesets. Use branch protection for merge hygiene, and use the license-compliance ruleset to make dependency policy mandatory before merge.

Where do I confirm that the check is really active? GitHub’s docs say to confirm that pull request annotations show license compliance results. If annotations appear in Evaluate mode and the same policy blocks merges in Active mode, the enforcement path is working as intended.