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:

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:

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

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.

See pricing and get the report tier