Skip to main content
Video tutorial · 1:22

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 valueWhat it doesEffect on the merge gate
OffoffLicenses are not checkedNone
ReportreportLicenses are checked; the result is shown on the merge request, marked (report only)None
EnforceblockLicenses 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 changeWaiting 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.

  1. 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-…).
  2. 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.
  3. Denied. A dependency is denied only when every way of meeting its expression needs a denied license: MIT OR GPL-3.0-only passes, since MIT can be chosen; MIT AND GPL-3.0-only is denied. A license on the Allowed licenses list is always usable, even when it also matches a denied pattern (for example GPL-2.0-only WITH Classpath-exception-2.0).
  4. 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Licenses)See ModesReportOff, Report, EnforcePolicyPolicy manager, company admin, platform admincontrols.licenses.mode (off, report, block)
Denied licensesLicenses that may not be used. An empty list denies nothingStrong copyleft: GPL-*, AGPL-*, SSPL-1.0, OSL-3.0, EUPL-1.2SPDX ids, one per line (comma-separated in the policy editor); * covers versionsCompany; policy overrideCompany: company admin. Policy: policy manager, company adminscanning.licenses.denied (null: the default list; []: none); controls.licenses.overrides.denied
Allowed licensesLicenses that are always allowed, and with Allow only the licenses below, the only onesEmptySPDX ids or expressions, exactly, without wildcardsCompany; policy overrideSamescanning.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 listOffOn, off (editor: Yes / No)Company; policy overrideSamescanning.licenses.allow_list_only; controls.licenses.overrides.allow_list_only
Licenses that cannot be checkedList 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 itList for reviewreview, blockCompany; policy override (shown in Enforce mode)Samescanning.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 scanning object 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​

StatusMessage
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.licenses with mode and overrides (denied, allowed, allow_list_only, unknown).
  • Company: scanning.licenses (denied, allowed, allow_list_only, unknown).
  • Merge request (GET /api/v1/merge-requests/{id}): in sca_scan, licenses_checked, licenses_denied, licenses_review, licenses_weak, license_findings (package, version, expression, outcome, reason), lookup_failed, lookup_error; and the result in decision.controls (control: "licenses").
  • Full result: GET /api/v1/companies/{id}/sca-results/{result_id}, field licenses (every added or changed dependency with its outcome: allowed, denied or review).

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Keep Unwanted Licenses OutYouTube ↗