Fail CI on a GPL or AGPL dependency
A license problem is cheap to fix on the pull request that introduces it and expensive to fix a year later, after it has shipped. This page is the mechanics of putting that check in CI for npm and Python projects: the gate command, its exit codes, a working GitHub Actions job, and what the tool will and will not catch.
The problem this prevents
Nobody adds a GPL dependency on purpose. What happens is that someone adds a small, useful package, and four levels down its tree sits something strong-copyleft or non-commercial. The lockfile diff is three hundred lines and the reviewer reads the two that look interesting. It merges, it ships, and nothing visible is wrong.
You find out later, from someone else. A customer's procurement review asks for your open-source inventory. An acquirer's counsel asks during diligence. Either way the discovery happens at the worst possible moment, and the fix is now a code change in something you have been shipping, not a one-line revert on a branch nobody merged.
A license gate in CI turns that into a failed check on a pull request. The cost of being wrong drops from a renegotiation to a few minutes.
The gate command
One command, no account, no key, no network calls:
npx --yes licenseproof@0.3.5 scan --fail-on conflict
It reads your lockfile, resolves every package's license from metadata and license files already on disk, and exits 1 if anything trips the threshold. Exit 0 means clean. Exit 2 means the tool itself could not run — a bad flag value, or no supported project at the given path — which is a different failure from "your dependencies have a problem", and worth keeping distinct in your pipeline. Pin the version as above so a new release cannot change your build's behaviour without you choosing it.
--fail-on conflict is the default, so the flag is there to be explicit rather than because it is required. The three values:
conflict— exit1only on CONFLICT-level packages. The sane default for a gate that people will not immediately disable.review— exit1on CONFLICT or REVIEW level, which also means unrecognized licenses. Stricter, and noisier at first; a reasonable target once you have cleared the backlog.never— always exit0and just report. Useful for the first week, while you find out what is actually in there.
Two other flags matter in CI. --project-license <id> sets the SPDX id a conflict is judged against, overriding what your manifest says; if nothing is declared anywhere, the tool assumes the strictest proprietary-equivalent rules and prints that assumption. --include-dev adds devDependencies, which are skipped by default. If your bundler inlines anything, run it both ways and look at the difference before deciding which one your gate uses.
GitHub Actions
The published action wraps the same CLI, adds the findings to the job summary, and uploads the machine-readable report as a build artifact:
name: License check
on: [push, pull_request]
jobs:
licenseproof:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
- run: npm ci
- uses: thrillhouse34/licenseproof-action@v1
with:
fail-on: conflict # conflict (default) | review | never
# Free CycloneDX SBOM, no key needed:
- run: npx --yes licenseproof@0.3.5 report --format sbom-cyclonedx --out sbom.cdx.json
The npm ci step is not optional for Node projects: the resolver reads licenses from what is installed on disk. The inputs you are most likely to set are fail-on, path (for a project that is not at the repo root), include-dev, project-license, and version, which is pinned by default. The report upload can be turned off with upload-artifact: false and renamed with artifact-name; the job-summary write can be turned off with summary: false.
The action also exposes its findings as outputs, so a later step can branch on them without re-parsing anything: outcome, total-packages, conflict-count, review-count, unknown-count, agpl-count, report-path, and summary-path.
Any other runner works the same way, because it is a plain npx call with no network access at scan time. On GitLab CI:
licenseproof:
image: node:22
stage: test
script:
- npm ci
- npx --yes licenseproof@0.3.5 scan --fail-on conflict
- npx --yes licenseproof@0.3.5 report --format sbom-cyclonedx --out sbom.cdx.json
artifacts:
paths: [sbom.cdx.json]
For a Python project, create the environment before scanning, so licenses resolve from installed metadata on disk rather than from declared version ranges:
- run: python -m venv .venv && .venv/bin/pip install -r requirements.txt
- uses: thrillhouse34/licenseproof-action@v1
with:
fail-on: conflict
A repo with both a package.json and a Python manifest is scanned as one combined job, not two.
What CONFLICT and REVIEW mean
The threshold you pick only makes sense if you know what it is counting. Every package lands in one of these:
- CONFLICT. A strong-copyleft license such as GPL in a proprietary project, any AGPL package regardless of what your project is licensed as, or a non-commercial-only license such as CC-BY-NC, BUSL, or SSPL in any commercial project. This is what
--fail-on conflictcatches. - REVIEW. Something a person has to decide, not something the tool can call. Weak copyleft such as LGPL or MPL; strong copyleft inside a permissively licensed project; a GPL-family project pulling in Apache-2.0, which has a known incompatibility; or a package whose own declared license field disagrees with its own classifiers. Caught by
--fail-on review. - UNKNOWN. No license signal resolved confidently. It carries REVIEW level, so
--fail-on reviewcatches it, but it is always reported in its own bucket rather than buried in the review list. Unknown does not mean safe. - AGPL noted, informational. Non-blocking, and separate from CONFLICT on purpose: this is the case where AGPL appears only as an unchosen branch of a license expression and the branch actually in force is clean. Flagged so you can see it, not so it can fail your build.
Each finding comes with a plain-English explanation of what the license is and why it matters for a project licensed like yours. How each license is resolved — the per-ecosystem order, the confidence levels, and where the resolver gives up — is documented separately.
The free CycloneDX artifact
One SBOM format is deliberately free and needs no license key:
npx --yes licenseproof@0.3.5 report --format sbom-cyclonedx --out sbom.cdx.json
That writes a CycloneDX 1.5 document, which is the SBOM format most CI pipelines and supply-chain scanners already consume. It is free so that licenseproof stays useful in an automated pipeline without anyone buying anything. Keep it as a build artifact and you have a per-commit record of what your dependency tree contained, which is a much easier question to answer later than reconstructing it from git.
Worth knowing: the SBOM formats embed a generated UUID and the scan timestamp, so two runs against an unchanged tree produce byte-different but equally valid files. Do not diff them expecting equality.
The paid report, for when someone asks
The gate is free forever. The artifacts a human reads are the paid tier: an audit-ready HTML report, the same report as a PDF with a true per-page provenance footer, a THIRD_PARTY_NOTICES.txt file, and an SPDX 2.3 SBOM. Add a key to the action and it generates them on the same run:
- uses: thrillhouse34/licenseproof-action@v1
with:
fail-on: conflict
license-key: ${{ secrets.LICENSEPROOF_LICENSE_KEY }}
report-formats: html,pdf,notices,sbom-cyclonedx,sbom-spdx
Pass the key from a secret, never as a literal. Leave license-key empty and nothing below it runs, so a half-configured workflow quietly degrades to the free scan instead of failing. The paid artifacts upload separately from the free report, under their own artifact name, and the report step runs even when the scan has already failed the job — which is exactly the run you want the full report for.
The HTML report is a single self-contained file with zero external references: it opens from a file:// URL forever, with no network access. The PDF is that same report printed through a browser you already have installed, so the two can never drift apart; it is the one format that needs Chrome, Chromium, or Edge present, and it fails cleanly with exit 2 and a message pointing you at --format html when none is found. See a real report, and generating a notices file covers that artifact in detail.
Honest limits
- It is informational, not legal. The categories and conflict calls come from fixed vendored SPDX data and a reviewed rule set. They are heuristics, not a legal opinion or a determination of your obligations. A green build is not a clearance.
- Unsupported package managers. Conda environments and Pipenv (
Pipfile,Pipfile.lock) are not detected or parsed at all. Noted as a gap, not as a near-term plan. - Monorepos are not supported yet. A workspace root scans only its own top-level
package.json, with a warning. Run the gate per package until that changes. - No lockfile means less certainty. Without one, npm falls back to declared
package.jsondependencies with a warning, and Python falls back to declaredpyproject.tomldependencies with versions marked unresolved. Both trees are incomplete by construction. Arequirements.txtcarries no transitive information at all, so everything in it reports as a direct dependency. - It only sees what is on disk. If the install step did not run, or a Python
.venvis missing, packages are listed but their licenses resolve to unknown rather than crashing. A wall of unknowns usually means a missing install step, not a wall of mystery packages. - Dependency paths are capped. A note like "at least N other paths" is a floor, not a total.
Add the gate
Drop the action into one workflow file and the next pull request that pulls in a GPL, AGPL, or non-commercial dependency fails its check instead of shipping. That part costs nothing, now and later. The reports for when someone asks you to prove it are $29 for an individual and $99 for agency use — perpetual, each including a year of reference-data updates, and still working after that.