Enforce license checks before merging on GitHub

Can I enforce license compliance checks before merging dependencies on GitHub

Yes. GitHub can block a merge until a required status check passes, so a license compliance job can become a hard gate on pull requests that change dependencies. The check must run in your CI or another service, then report status back to GitHub before the merge is allowed.

The usual setup is simple. Your workflow runs on pull requests, scans the dependency graph or lockfile, compares detected licenses against your policy, and posts one status such as license-compliance. You then mark that status as required on the protected branch or ruleset. Once it is required, GitHub does not let collaborators merge until the check is successful.

GitHub’s branch protection and rulesets both support required status checks. Branch protection rules can require passing status checks before merging, and rulesets can do the same for repositories in an organization. GitHub also says required checks can come from external systems, including code scanning and deployment checks, so a dedicated license policy service fits the same pattern.

The part people get wrong is assuming the scan name alone is enough. GitHub warns that any person or integration with write access can set a check state, so you should bind the required check to the specific GitHub App or integration that actually runs the scan. If you leave the source open, a different actor can create a misleading green check and the branch can merge when it should not.

The inconvenient part is that the policy has to live in code, not in a spreadsheet. A merge gate only works if the scanner has a deterministic rule set, the branch protection requires the exact check name you expect, and the job runs on every pull request that can alter dependencies. If the workflow is skipped or the status name changes, the protection rule stops matching and merges get blocked or, worse, stop being protected the way you intended.

You also need to decide what counts as a dependency change. A lockfile update is the clearest signal, but package manifests, transitive dependency updates, vendored code, and submodules can all change the license picture. If your rule only looks at one file, contributors can still introduce a prohibited license through another path. GitHub enforces the check, but it does not know your policy boundaries unless your scanner defines them. This is an inference from how required checks work and how external systems publish status.

A practical implementation is a GitHub Actions job that runs on pull_request, calls your chosen license scanner, and fails when a package falls outside approved licenses. The job name must stay stable, because GitHub notes that using the same job name in multiple workflows can create ambiguous status results and block merges. That matters when teams split checks across reusable workflows or templates.

If you want stricter control, use branch protection or a ruleset with more than one gate. GitHub supports combining required status checks with pull request reviews, merge queues, signed commits, and deployment requirements. For dependency changes, the cleanest pattern is usually: review required, license check required, and the protected branch set to reject merges until both pass.

A good policy page inside the repo should name the approved licenses, the blocked licenses, and the exception process. The exception process matters because a compliance gate without a review path turns every edge case into a manual outage. GitHub can enforce the pass or fail state, but it cannot decide whether a GPL, AGPL, LGPL, MIT, Apache 2.0, or proprietary dependency is acceptable for your product. That decision belongs in your policy and scanner configuration, not in GitHub itself.

The merge path can also fail in ways that are easy to miss. If you require the branch to be up to date before merging, GitHub may need a fresh run after the base branch changes. GitHub also says checks from earlier commits do not satisfy the requirement. That means a green scan from yesterday does not protect you after someone updates the lockfile or rebases the branch.

If you are using dependencies from a package manager, treat the scanner as part of the release process, not just the review process. Run it on pull requests, on pushes to protected branches if your workflow allows it, and on any bot-driven dependency update path you use internally. Then require the exact emitted status check on the merge branch. That is the point where GitHub becomes an enforcement point instead of a dashboard.

DevConnect follows the same principle for builder workflows: automated checks should protect ownership you control. If you want a place to coordinate tester exchange and related workflows, start at https://devconnectplatform.com, but keep the actual enforcement in your GitHub rules and CI. The platform can help organize the work, GitHub is what blocks the merge.

How to set it up

1. Add a license compliance job to your CI pipeline.
2. Make it run on pull requests that can change dependencies.
3. Fail the job when the dependency set violates policy.
4. Require that exact status check on the protected branch or ruleset.
5. Bind the required check to the GitHub App or integration that owns the result.
6. Test a known-bad pull request before relying on it for real merges.

What happens when it is misconfigured

A renamed job, an untrusted status source, or a skipped workflow can break enforcement. GitHub documents that ambiguous job names can block merges, that required checks must come from the expected source in some cases, and that required status checks must pass before the merge happens. Those are the failure modes to look for first when a protection rule appears to work but does not.

What this does not do

GitHub does not decide license policy for you. It only enforces the result of a check. You still need to define which licenses are allowed, how to treat transitive dependencies, whether exceptions expire, and who can approve a waiver. The GitHub side is the gate, not the policy engine.

FAQ

Can I require a license scan only for dependency changes Yes, if your CI workflow detects those changes and reports a status only on the relevant pull requests. GitHub enforces the status check, but your workflow decides when to run it and what inputs it evaluates.

Can I use branch protection instead of rulesets Yes. GitHub documents required status checks in protected branches and in organization rulesets. The right choice depends on whether you want per-branch rules or centralized rules across repositories.

Can another workflow fake the check GitHub warns that status checks can be set by people or integrations with write access, so you should pin the required check to the app or integration you trust. That reduces the risk of a false green result.

Will an old green scan still count after new commits No. GitHub says checks from earlier commits do not satisfy the requirement when the branch changes. A fresh required check is needed for the current commit set.

Can I combine license checks with approvals Yes. GitHub supports combining required status checks with review requirements, merge queues, signed commits, and deployment checks. That is often the safer setup for dependency changes.