License compliance

Introduced in GitLab 11.0.

If you’re using GitLab CI/CD, you can use License Compliance to search your project’s dependencies for their licenses. You can then decide whether to allow or deny the use of each license. For example, if your application uses an external (open source) library whose license is incompatible with yours, then you can deny the use of that license.

To detect the licenses in use, License Compliance uses the License Finder scan tool that runs as part of the CI/CD pipeline. The License Compliance job is not dependent on any other job in a pipeline.

For the job to activate, License Finder needs to find a compatible package definition in the project directory. For details, see the Activation on License Finder documentation. GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge request. Denied licenses are indicated by a x red icon next to them as well as new licenses that need a decision from you. In addition, you can manually allow or deny licenses in your project’s license compliance policy section. If a denied license is detected in a new commit, GitLab blocks any merge requests containing that commit and instructs the developer to remove the license.

note
If the license compliance report doesn’t have anything to compare to, no information is displayed in the merge request area. That is the case when you add the license_scanning job in your .gitlab-ci.yml for the first time. Consecutive merge requests have something to compare to and the license compliance report is shown properly.

The results are saved as a License Compliance report artifact that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available.

caution
License Compliance Scanning does not support run-time installation of compilers and interpreters.

License Compliance Widget

You can select a license to see more information.

When GitLab detects a Denied license, you can view it in the license list.

License List

You can view and modify existing policies from the policies tab.

Edit Policy

License expressions

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 OR, WITH) is tracked in this epic.

Supported languages and package managers

The following languages and package managers are supported.

Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5.

Language Package managers Notes
JavaScript Bower, npm (7 and earlier)  
Go Godep (deprecated), go mod  
Java Gradle, Maven  
.NET NuGet The .NET Framework is supported via the mono project. There are, however, some limitations. The scanner doesn’t support Windows-specific dependencies and doesn’t report dependencies of your project’s listed dependencies. Also, the scanner always marks detected licenses for all dependencies as unknown.
Python pip Python is supported through requirements.txt and Pipfile.lock.
Ruby gem  

Experimental support

The following languages and package managers are supported experimentally. The reported licenses might be incomplete or inaccurate.

Language Package managers
JavaScript Yarn
Go go get, gvt, glide, dep, trash, govendor
Erlang Rebar
Objective-C, Swift Carthage, CocoaPods v0.39 and below
Elixir Mix
C++/C Conan
Rust Cargo
PHP Composer

Enable License Compliance

To enable License Compliance in your project’s pipeline, either:

Include the License Scanning template

Prerequisites:

  • GitLab Runner available, with the docker executor. If you’re using the shared runners on GitLab.com, this is enabled by default.
  • License Scanning runs in the test stage, which is available by default. If you redefine the stages in the .gitlab-ci.yml file, the test stage is required.

To include the License-Scanning.gitlab-ci.yml template, add it to your .gitlab-ci.yml file:

include:
  - template: Security/License-Scanning.gitlab-ci.yml

The included template creates a license_scanning job in your CI/CD pipeline and scans your dependencies to find their licenses.

Available CI/CD variables

License Compliance can be configured using CI/CD variables.

CI/CD variable Required Description
ADDITIONAL_CA_CERT_BUNDLE no Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects).
ASDF_JAVA_VERSION no Version of Java to use for the scan.
ASDF_NODEJS_VERSION no Version of Node.js to use for the scan.
ASDF_PYTHON_VERSION no Version of Python to use for the scan. Configuration
ASDF_RUBY_VERSION no Version of Ruby to use for the scan.
GRADLE_CLI_OPTS no Additional arguments for the Gradle executable. If not supplied, defaults to --exclude-task=test.
LICENSE_FINDER_CLI_OPTS no Additional arguments for the license_finder executable. For example, if you have multiple projects in nested directories, you can update your .gitlab-ci.yml template to specify a recursive scan, like LICENSE_FINDER_CLI_OPTS: '--recursive'.
LM_JAVA_VERSION no Version of Java. If set to 11, Maven and Gradle use Java 11 instead of Java 8. Configuration
LM_PYTHON_VERSION no Version of Python. If set to 3, dependencies are installed using Python 3 instead of Python 2.7. Configuration
MAVEN_CLI_OPTS no Additional arguments for the mvn executable. If not supplied, defaults to -DskipTests.
PIP_INDEX_URL no Base URL of Python Package Index (default: https://pypi.org/simple/).
SECURE_ANALYZERS_PREFIX no Set the Docker registry base address to download the analyzer from.
SETUP_CMD no Custom setup for the dependency installation (experimental).

Installing custom dependencies

Introduced in GitLab 11.4.

The license_finder image already embeds many auto-detection scripts, languages, and packages. Nevertheless, it’s almost impossible to cover all cases for all projects. That’s why sometimes it’s necessary to install extra packages, or to have extra steps in the project automated setup, like the download and installation of a certificate. For that, a SETUP_CMD CI/CD variable can be passed to the container, with the required commands to run before the license detection.

<