- Supported languages and package managers
- License expressions
- Blocking merge requests based on detected licenses
- Running in an offline environment
Jobs/License-Scanning.gitlab-ci.ymltemplate from your CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do so by setting the
LICENSE_MANAGEMENT_VERSION CIvariable to
4. This variable can be set at the project, group or instance level.
To detect the licenses in use, License Compliance relies on running the Dependency Scanning CI Jobs, and analyzing the CycloneDX Software Bill of Materials (SBOM) generated by those jobs. Other 3rd party scanners may also be used as long as they produce a CycloneDX file with a list of dependencies for one of our supported languages. This method of scanning is also capable of parsing and identifying over 500 different types of licenses, as defined in the SPDX list. Licenses not in the SPDX list are reported as “Unknown”.
To enable License scanning of CycloneDX files:
- Enable Dependency Scanning and ensure that its prerequisites are met.
- On GitLab self-managed only, you can choose package registry metadata to synchronize in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain
storage.googleapis.com. If you have limited or no network connectivity then please refer to the documentation section running in an offline environment for further guidance.
License scanning is supported for the following languages and package managers:
The supported files and versions are the ones supported by Dependency Scanning.
GitLab has limited support for composite licenses.
License compliance can read multiple licenses, but always considers them combined using the
AND operator. For example,
if a dependency has two licenses, and one of them is allowed and the other is denied by the project policy,
GitLab evaluates the composite license as denied, as this is the safer option.
The ability to support other license expression operators (like
WITH) is tracked
in this epic.
Users can require approval for merge requests based on the licenses that are detected by configuring a license approval policy.
For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required to successfully scan CycloneDX reports for licenses. For more information, see the offline quick start guide.
Ensure that the CycloneDX file adheres to the CycloneDX JSON specification. This specification does not permit duplicate entries. Projects that contain multiple SBOM files should either report each SBOM file up as individual CI report artifacts or they should ensure that duplicates are removed if the SBOMs are merged as part of the CI pipeline.
You can validate CycloneDX SBOM files against the
CycloneDX JSON specification as follows:
$ docker run -it --rm -v "$PWD:/my-cyclonedx-sboms" -w /my-cyclonedx-sboms cyclonedx/cyclonedx-cli:latest cyclonedx validate --input-version v1_4 --input-file gl-sbom-all.cdx.json Validating JSON BOM... BOM validated successfully.
If the JSON BOM fails validation, for example, because there are duplicate components:
Validation failed: Found duplicates at the following index pairs: "(A, B), (C, D)" #/properties/components/uniqueItems
This issue can be fixed by updating the CI template to use jq to remove the duplicate components from the
gl-sbom-*.cdx.json report by overriding the job definition that produces the duplicate components. For example, the following removes duplicate components from the
gl-sbom-gem-bundler.cdx.json report file produced by the
include: - template: Jobs/Dependency-Scanning.gitlab-ci.yml gemnasium-dependency_scanning: after_script: - apk update && apk add jq - jq '.components |= unique' gl-sbom-gem-bundler.cdx.json > tmp.json && mv tmp.json gl-sbom-gem-bundler.cdx.json
License scanning changes (released in GitLab 15.9) required a significant amount of additional disk space to be available on the instances. This issue was resolved in GitLab 16.3 by the Reduce package metadata table on-disk footprint epic. But if your instance was running license scanning between GitLab 15.9 and 16.3, you may want to remove the unneeded data.
To remove the unneeded data:
Feature.enabled?(:package_metadata_synchronization) && Feature.disable(:package_metadata_synchronization)
Check if there is deprecated data in the database:
If there is deprecated data in the database, remove it by running the following commands in order:
ActiveRecord::Base.connection.execute('SET statement_timeout TO 0') PackageMetadata::PackageVersionLicense.delete_all PackageMetadata::PackageVersion.delete_all