Licenses
The Licenses control checks the licenses of the dependencies a merge request adds or upgrades against the company's license policy: licenses you do not accept (by default strong copyleft such as GPL and AGPL), licenses you always accept, and what to do when a license cannot be determined. License data comes from deps.dev.
Whether a merge request is checked, and whether a denied license holds it, is set per change policy (policy editor, Checks tab, row Licenses). The license policy itself is a company setting (the company's Scanning tab → Dependencies, card Licenses), which a policy can override.
The check runs inside the dependency scan: it reads the same manifests, with the same supported files, path filters and limits, even when the policy's Dependency scan control is off.
Modes
| Mode (label in the UI) | API value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | Licenses are not checked | None |
| Report | report | Licenses are checked; the result is shown on the merge request, marked (report only) | None |
| Enforce | block | Licenses are checked; a denied license holds the merge, and so does a license that cannot be checked when the company or policy says Hold the change | Waiting while the scan runs; Blocked on a denied license, a held unknown license, failed package lookups, or a scan that could not be completed |
A new policy starts with Report. A policy saved without a mode (for example through the API) is saved with Report, and the editor and the list's chips show it as such.
Which dependencies are checked
Every dependency the change adds, and the new version of every dependency it upgrades or downgrades, as read from the changed manifests. License data is available for the Go, npm, PyPI, Maven, crates.io, NuGet and RubyGems ecosystems; a dependency of another ecosystem is listed for review ("no license data for the … ecosystem"). Answers about a package version are reused for up to 7 days.
How a license is judged
A dependency's license is read as an SPDX expression. When a package declares several licenses, all of them apply.
- Cannot be judged → review. The dependency is listed for review when the license database does not know the version, it is named by a version range (no version to look up), it declares no license, its license has no SPDX id, the expression is not valid SPDX, or it uses a custom license (
LicenseRef-…). - Allow list only. With Allow only the licenses below on, a license expression that cannot be met with allowed licenses alone is denied ("not on the allow list"); with an empty allow list, every license is denied.
- Denied. A dependency is denied only when every way of meeting its expression needs a denied license:
MIT OR GPL-3.0-onlypasses, since MIT can be chosen;MIT AND GPL-3.0-onlyis denied. A license on the Allowed licenses list is always usable, even when it also matches a denied pattern (for exampleGPL-2.0-only WITH Classpath-exception-2.0). - Allowed. Anything else passes. Weak copyleft licenses (
LGPL-*,MPL-*,EPL-*,CDDL-*) pass but are counted, because they oblige sharing changes made to the library itself.
A denied or to-review dependency accepted by an active exception for its package does not count; the merge request is evaluated again when an exception is created, revoked or expires.
Denied patterns match a license by its SPDX id, ignoring case; * covers versions (GPL-*). GPL-2.0 and GPL-2.0-only are treated as the same license.
Settings
Company admins change the company's settings on the Scanning tab (PUT /api/v1/companies/{id} with scanning.licenses). The policy editor shows the overrides under the Licenses row; each starts on Company setting (…). A list override is chosen with This policy's list, which opens Denied licenses for this policy (or Allowed licenses for this policy).
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row Licenses) | See Modes | Report | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.licenses.mode (off, report, block) |
| Denied licenses | Licenses that may not be used. An empty list denies nothing | Strong copyleft: GPL-*, AGPL-*, SSPL-1.0, OSL-3.0, EUPL-1.2 | SPDX ids, one per line (comma-separated in the policy editor); * covers versions | Company; policy override | Company: company admin. Policy: policy manager, company admin | scanning.licenses.denied (null: the default list; []: none); controls.licenses.overrides.denied |
| Allowed licenses | Licenses that are always allowed, and with Allow only the licenses below, the only ones | Empty | SPDX ids or expressions, exactly, without wildcards | Company; policy override | Same | scanning.licenses.allowed; controls.licenses.overrides.allowed |
| Allow only the licenses below (policy editor: Only allowed licenses) | Every license not on the allowed list is denied. Use it where legal approved a short list | Off | On, off (editor: Yes / No) | Company; policy override | Same | scanning.licenses.allow_list_only; controls.licenses.overrides.allow_list_only |
| Licenses that cannot be checked | List for review: unknown, custom or non-standard licenses (and packages deps.dev does not know) are listed; they do not hold the change. Hold the change: such a dependency holds the change in Enforce mode until someone reviews it | List for review | review, block | Company; policy override (shown in Enforce mode) | Same | scanning.licenses.unknown; controls.licenses.overrides.unknown |
Entries that are not SPDX license ids, and wildcards in the allowed list, are refused on save.
Notes:
- A policy override list replaces the company's list, even when empty; leaving it out (
null) keeps the company's. - The company's
scanningobject is saved as a whole: fields left out take their defaults. - Licenses that cannot be checked is applied each time the merge request is evaluated. The lists and Allow only the licenses below take effect at the next scan (a new commit or a re-scan).
- What a failed scan or a failed lookup does is the dependency scan's When the scan cannot finish setting (see Dependency scan).
What the control says
| Status | Message |
|---|---|
| Pending | "Checking the licenses of new dependencies." |
| Passed | "No denied licenses." with, when there are some, "N license(s) to review (unknown or not standard)." and "N weak copyleft (changes to those libraries must be shared)." |
| Failed | "N new dependenc(ies) with a denied license." |
| Failed | "N new dependenc(ies) with a license that could not be checked; review them." (under Hold the change) |
| Failed | "The package data of N new dependency version(s) could not be read from deps.dev: … Rescan once deps.dev answers." |
| Failed | "The dependency scan could not be completed: … Fix the cause and rescan." |
When it runs
With the dependency scan: once per commit, on Re-scan on the merge request page's Dependency scan (SCA) card (POST /api/v1/merge-requests/{id}/rescan with {"scan": "sca"}), and after a failure when the company or policy retries automatically. A scan of the latest commit that was made while the control was off runs again once the policy turns it on. See Dependency scan.
What the merge request shows
In the Dependency scan (SCA) card, a Licenses section shows No denied licenses. (with the weak copyleft count), or a table of the denied and to-review dependencies, denied first, with Package, License and Result (Denied, or Review: and the reason). Every denied dependency is listed (so each can be accepted by an exception); to-review ones are added up to 50 rows in all.
The Merge Pilot: Dependency Scan comment in the VCS includes a Licenses table with the denied and to-review dependencies.
GitLab and GitHub
The check is the same on both.
Audit
The result is part of the sca_scan entry (with licenses_denied and licenses_review counts), written when the result changes. Re-scans are sca_rescan. See Audit log.
API
- Policy:
controls.licenseswithmodeandoverrides(denied,allowed,allow_list_only,unknown). - Company:
scanning.licenses(denied,allowed,allow_list_only,unknown). - Merge request (
GET /api/v1/merge-requests/{id}): insca_scan,licenses_checked,licenses_denied,licenses_review,licenses_weak,license_findings(package,version,expression,outcome,reason),lookup_failed,lookup_error; and the result indecision.controls(control: "licenses"). - Full result:
GET /api/v1/companies/{id}/sca-results/{result_id}, fieldlicenses(every added or changed dependency with its outcome:allowed,deniedorreview).
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →