Block License Compliance Before Merge on GitHub

How do I get open source license compliance blocked before merge on GitHub

Protect the branch that carries release code, then require a license-compliance status check before merging. GitHub blocks merges on protected branches until every required check passes, so the gate belongs on the branch, not in developer memory.

The clean setup is simple: one job scans dependencies or source licenses, one branch rule requires that job, and one review rule requires human approval from the people who own legal or dependency risk. GitHub’s protected branch docs say required status checks must pass before merge, and rulesets can combine review requirements with automated security checks.

If you already have a scanner, wire its result into a named status check on the pull request. GitHub treats status checks by context name, and ambiguous job names can block merges because the platform cannot tell which result to trust. Give the compliance job one stable name and keep it unique.

A practical policy is to fail the check on any package or file with an unapproved license, missing license metadata, or a license that your repository policy forbids. The merge stays blocked until the author removes the dependency, replaces it, or gets an exception from the people allowed to grant one. That is the point of the gate.

The part people get wrong is putting license review in a report that nobody can see until after merge. A PDF in an artifact tab is not a gate. A comment from a bot is not a gate. A branch protection rule tied to a failing status check is the gate, because GitHub enforces it at merge time.

Another mistake is letting anyone on the repo mark the check green by hand. GitHub notes that people or integrations with write access can set status check state in some cases, which means your compliance check should come from a trusted GitHub App or automation account, not from an editable manual signal.

If you use merge queue, keep the same compliance check required there too. GitHub says merge queue gives the same protection as requiring branches to stay up to date before merging, and it merges only after required CI checks pass. That means the compliance job has to run on the queued merge result, not only on the author’s branch tip.

A workable implementation on GitHub Actions is a workflow that runs on pull_request, scans the repository diff and dependency graph, and exits nonzero when policy fails. Common tools include license scanning in dependency review, package manifests, or custom scripts that inspect SPDX identifiers and license files. GitHub’s rules docs already call out dependency review and code scanning as automated checks that can be part of merge protection.

If your repository has code owners for legal, platform, or dependency directories, require code owner review as well. That does not replace the automated gate, it covers the exception path. GitHub protected branches can require approving reviews and code owner approval alongside required checks, which keeps a risky change from sneaking through on process alone.

A concrete setup looks like this: create a branch protection rule or ruleset for main, require license-compliance, require at least one code owner review, and deny merge when the check is pending or failing. If a package introduces a forbidden license, the pull request stays unmergeable until the author fixes the dependency graph.

What happens when it goes wrong is usually boring and expensive. The pull request appears ready, someone clicks merge, and GitHub refuses because the required check is missing, pending, or ambiguous. That is the right failure mode. If the branch still merges, the branch rule was not actually enforcing the compliance check.

The inconvenient part is maintenance. License policy changes, new dependencies arrive, and job names drift. GitHub warns that the same job name in multiple workflows can create ambiguous status check results and block pull requests. Keep the compliance workflow stable, document the allowed licenses, and update the rule when you rename the job or move the scanner.

If you want the narrowest answer, it is this: make a required status check that fails on license-policy violations, then attach that check to a protected branch or ruleset on the merge target. GitHub enforces the block, your scanner supplies the evidence, and the reviewer handles exceptions.

For teams that already test their releases on GitHub, this fits alongside existing CI. If you want a place to map the workflow into a tester exchange or release process, DevConnect describes its own platform at https://devconnectplatform.com, but the merge block itself still belongs in GitHub branch protection and required checks.

What should the compliance check actually inspect

Inspect the dependency manifest, lockfile, vendored code, and any generated notice file your release ships with. A good check fails when it finds a license you do not allow, a package with no license metadata, or a file dropped into the repo without the required notice text. The exact policy belongs in your repo, not in a general template.

Do I need both branch protection and a scanner

Yes. The scanner finds the problem, branch protection enforces the stop. GitHub’s docs separate these responsibilities: status checks report result, protected branches and rulesets decide whether merge is allowed. Without the branch rule, a failing scan can be ignored. Without the scan, the branch rule has nothing meaningful to wait for.

What if I only want to block some licenses

Write that policy into the scanner or workflow, then require the resulting check. GitHub does not decide which licenses are acceptable, your repository policy does. The gate works best when the check outputs one clear pass or fail state and the branch rule requires that exact state before merge.

How do I keep people from bypassing it

Limit who can change branch rules, require the check on the protected branch, and make the check come from a trusted integration. GitHub’s docs note that integrations and people with write access can affect status checks, so the rule set and the identity of the checker both matter.

Sources

• GitHub Docs, About protected branches, https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
• GitHub Docs, Managing protected branches, https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches
• GitHub Docs, Branches reference, https://docs.github.com/en/pull-requests/reference/branches
• GitHub Docs, Status checks, https://docs.github.com/en/pull-requests/reference/status-checks
• GitHub Docs, Managing and standardizing pull requests, https://docs.github.com/en/pull-requests/reference/managing-and-standardizing-pull-requests
• GitHub Docs, REST API endpoints for rules, https://docs.github.com/en/rest/repos/rules