License Compliance (ULTIMATE)

Introduced in GitLab Ultimate 11.0.

Overview

If you are using GitLab CI/CD, you can search your project dependencies for their licenses using License Compliance.

You can take advantage of License Compliance by either including the job in your existing .gitlab-ci.yml file or by implicitly using Auto License Compliance that is provided by Auto DevOps.

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 will be clearly visible with an x red icon next to them as well as new licenses which need a decision from you. In addition, you can manually allow or deny licenses in your project's settings.

NOTE: Note: If the license compliance report doesn't have anything to compare to, no information will be 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 will have something to compare to and the license compliance report will be shown properly.

If you are a project or group Maintainer, you can click on a license to be given the choice to allow it or deny it.

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

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

Use cases

It helps you find what licenses your project uses in its dependencies, and decide for each of then whether to allow it or forbid it. For example, your application is using an external (open source) library whose license is incompatible with yours.

Supported languages and package managers

The following languages and package managers are supported.

Language	Package managers	Scan Tool
JavaScript	Bower, npm	License Finder
Go	Godep, go mod	License Finder
Java	Gradle, Maven	License Finder
.NET	Nuget (.NET Framework is supported via the mono project. Windows specific dependencies are not supported at this time.)	License Finder
Python	pip (Python is supported through requirements.txt and Pipfile.lock.)	License Finder
Ruby	gem	License Finder
Objective-C, Swift	Carthage	License Finder

NOTE: Note:

Java 8 and Gradle 1.x projects are not supported.

Experimental support

The following languages and package managers are supported experimentally, which means that the reported licenses might be incomplete or inaccurate.

Language	Package managers	Scan Tool
JavaScript	yarn	License Finder
Go	go get, gvt, glide, dep, trash, govendor	License Finder
Erlang	rebar	License Finder
Objective-C, Swift	CocoaPods v0.39 and below	License Finder
Elixir	mix	License Finder
C++/C	conan	License Finder
Scala	sbt	License Finder
Rust	cargo	License Finder
PHP	composer	License Finder

Requirements

To run a License Compliance scanning job, you need GitLab Runner with the docker executor.

Configuration

For GitLab 12.8 and later, to enable License Compliance, you must include the License-Scanning.gitlab-ci.yml template that's provided as a part of your GitLab installation. For older versions of GitLab from 11.9 to 12.7, you must include the License-Management.gitlab-ci.yml template. For GitLab versions earlier than 11.9, you can copy and use the job as defined that template.

NOTE: Note: GitLab 13.0 removes the License-Management.gitlab-ci.yml template. Use License-Scanning.gitlab-ci.yml instead.

Add the following to your .gitlab-ci.yml file:

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

The included template will create a license_scanning job in your CI/CD pipeline and scan your dependencies to find their licenses.

NOTE: Note: Before GitLab 12.8, the license_scanning job was named license_management. GitLab 13.0 removes the license_management job, so you're advised to migrate to the license_scanning job and used the new License-Scanning.gitlab-ci.yml template.

The results will be 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. Behind the scenes, the GitLab License Compliance Docker image is used to detect the languages/frameworks and in turn analyzes the licenses.

The License Compliance settings can be changed through environment variables by using the variables parameter in .gitlab-ci.yml.

Available variables

License Compliance can be configured using environment variables.

Environment 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.
`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 your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`.
`LM_JAVA_VERSION`	no	Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8.
`LM_PYTHON_VERSION`	no	Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7.
`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 Ultimate 11.4.

The license_management 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 LICENSE_MANAGEMENT_SETUP_CMD environment variable can be passed to the container, with the required commands to run before the license detection.

If present, this variable will override the setup step necessary to install all the packages of your application (e.g.: for a project with a Gemfile, the setup step could be bundle install).

For example:

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

variables:
  LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh

In this example, my-custom-install-script.sh is a shell script at the root directory of your project.

Overriding the template

CAUTION: Deprecation: Beginning in GitLab 13.0, the use of only and except is no longer supported. When overriding the template, you must use rules instead.

If you want to override the job definition (for example, change properties like variables or dependencies), you need to declare a license_scanning job after the template inclusion and specify any additional keys under it. For example:

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

license_scanning:
  variables:
    CI_DEBUG_TRACE: "true"

Configuring Maven projects

The License Compliance tool provides a MAVEN_CLI_OPTS environment variable which can hold the command line arguments to pass to the mvn install command which is executed under the hood. Feel free to use it for the customization of Maven execution. For example:

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

license_scanning:
  variables:
    MAVEN_CLI_OPTS: --debug

mvn install runs through all of the build life cycle stages prior to install, including test. Running unit tests is not directly necessary for the license scanning purposes and consumes time, so it's skipped by having the default value of MAVEN_CLI_OPTS as -DskipTests. If you want to supply custom MAVEN_CLI_OPTS and skip tests at the same time, don't forget to explicitly add -DskipTests to your options. If you still need to run tests during mvn install, add -DskipTests=false to MAVEN_CLI_OPTS.

Using private Maven repos

If you have a private Maven repository which requires login credentials, you can use the MAVEN_CLI_OPTS environment variable.

Read more on how to use private Maven repos.

You can also use MAVEN_CLI_OPTS to connect to a trusted Maven repository that uses a self-signed or internally trusted certificate. For example:

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

license_scanning:
  variables:
    MAVEN_CLI_OPTS: -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.ignore.validity.dates=true -Dmaven.wagon.http.ssl.insecure=true

Alternatively, you can use a Java key store to verify the TLS connection. For instructions on how to generate a key store file, see the Maven Guide to Remote repository access through authenticated HTTPS.

Selecting the version of Python

Introduced in GitLab Ultimate 12.0.

In GitLab 12.2, Python 3.5 became the default.

In GitLab 12.7, Python 3.8 became the default.

License Compliance uses Python 3.8 and pip 19.1 by default. If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 by setting the LM_PYTHON_VERSION environment variable to 2.

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

license_scanning:
  variables:
    LM_PYTHON_VERSION: 2

Custom root certificates for Python

You can supply a custom root certificate to complete TLS verification by using the ADDITIONAL_CA_CERT_BUNDLE environment variable.

To bypass TLS verification, you can use a custom pip.conf file to configure trusted hosts.

The following gitlab-ci.yml file uses a before_script to inject a custom pip.conf:

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

license_scanning:
  variables:
    PIP_INDEX_URL: 'https://pypi.example.com/simple/'
  before_script:
    - mkdir -p ~/.config/pip/
    - cp pip.conf ~/.config/pip/pip.conf

The pip.conf allows you to specify a list of trusted hosts:

[global]
trusted-host = pypi.example.com

Using private Python repos

If you have a private Python repository you can use the PIP_INDEX_URL environment variable to specify its location. It's also possible to provide a custom pip.conf for additional configuration.

Configuring NPM projects

You can configure NPM projects by using an .npmrc file.

Using private NPM registries

If you have a private NPM registry you can use the registry setting to specify its location.

For example:

registry = https://npm.example.com

Custom root certificates for NPM

You can supply a custom root certificate to complete TLS verification by using the ADDITIONAL_CA_CERT_BUNDLE environment variable.

To disable TLS verification you can provide the strict-ssl setting.

For example:

strict-ssl = false

Configuring Yarn projects

You can configure Yarn projects by using a .yarnrc.yml file.

Using private Yarn registries

If you have a private Yarn registry you can use the npmRegistryServer setting to specify its location.

For example:

npmRegistryServer: "https://npm.example.com"

Custom root certificates for Yarn

You can supply a custom root certificate to complete TLS verification by using the ADDITIONAL_CA_CERT_BUNDLE environment variable.

Configuring Bower projects

You can configure Bower projects by using a .bowerrc file.

Using private Bower registries

If you have a private Bower registry you can use the registry setting to specify its location.

For example:

{
  "registry": "https://registry.bower.io"
}

Custom root certificates for Bower

You can supply a custom root certificate to complete TLS verification by using the ADDITIONAL_CA_CERT_BUNDLE environment variable, or by specifying a ca setting in a .bowerrc file.

Configuring Conan projects

You can configure Conan projects by adding a .conan directory to your project root. The project root serves as the CONAN_USER_HOME.

Consult the Conan documentation for a list of settings that you can apply.

The license_scanning job runs in a Debian 10 Docker image. The supplied image ships with some build tools such as CMake and GCC. However, not all project types are supported by default. To install additional tools needed to compile dependencies, use a before_script to install the necessary build tools using the apt package manager. For a comprehensive list, consult the Conan documentation.

The default Conan configuration sets CONAN_LOGIN_USERNAME to ci_user, and binds CONAN_PASSWORD to the CI_JOB_TOKEN for the running job. This allows Conan projects to fetch packages from a GitLab Conan Repository if a GitLab remote is specified in the .conan/remotes.json file.

To override the default credentials specify a CONAN_LOGIN_USERNAME_{REMOTE_NAME} matching the name of the remote specified in the .conan/remotes.json file.

NOTE: Note: MSBuild projects aren't supported. The license_scanning image ships with Mono and MSBuild. Additional setup may be required to build packages for this project configuration.

Using private Conan registries

By default, Conan uses the conan-center remote. For example:

{
 "remotes": [
  {
   "name": "conan-center",
   "url": "https://conan.bintray.com",
   "verify_ssl": true
  }
 ]
}

To fetch dependencies from an alternate remote, specify that remote in a .conan/remotes.json. For example:

{
 "remotes": [
  {
   "name": "gitlab",
   "url": "https://gitlab.com/api/v4/packages/conan",
   "verify_ssl": true
  }
 ]
}

If credentials are required to authenticate then you can configure a protected variable following the naming convention described in the CONAN_LOGIN_USERNAME documentation.

Custom root certificates for Conan

You can provide custom certificates by adding a .conan/cacert.pem file to the project root and setting CA_CERT_PATH to .conan/cacert.pem.

If you specify the ADDITIONAL_CA_CERT_BUNDLE environment variable, this variable's X.509 certificates are installed in the Docker image's default trust store and Conan is configured to use this as the default CA_CERT_PATH.

Configuring Go projects

To configure Go modules based projects, specify environment variables in the license_scanning job's variables section in .gitlab-ci.yml.

If a project has vendored its modules, then the combination of the vendor directory and mod.sum file are used to detect the software licenses associated with the Go module dependencies.

Using private Go registries

You can use the GOPRIVATE and GOPROXY environment variables to control where modules are sourced from. Alternatively, you can use go mod vendor to vendor a project's modules.

Custom root certificates for Go

You can specify the -insecure flag by exporting the GOFLAGS environment variable. For example:

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

license_scanning:
  variables:
    GOFLAGS: '-insecure'

Migration from `license_management` to `license_scanning`

In GitLab 12.8 a new name for license_management job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. GitLab 13.0 drops support for license_management. If you're using a custom setup for License Compliance, you're required to update your CI config accordingly:

Change the CI template to License-Scanning.gitlab-ci.yml.
Change the job name to license_scanning (if you mention it in .gitlab-ci.yml).
Change the artifact name to license_scanning, and the file name to gl-license-scanning-report.json (if you mention it in .gitlab-ci.yml).

For example, the following .gitlab-ci.yml:

include:
  - template: License-Management.gitlab-ci.yml

license_management:
  artifacts:
    reports:
      license_management: gl-license-management-report.json

Should be changed to:

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

license_scanning:
  artifacts:
    reports:
      license_scanning: gl-license-scanning-report.json

If you use the license_management artifact in GitLab 13.0 or later, the License Compliance job generates this error:

WARNING: Uploading artifacts to coordinator... failed id=:id responseStatus=400 Bad Request status=400 Bad Request token=:sha

FATAL: invalid_argument

If you encounter this error, follow the instructions described in this section.

Running License Compliance in an offline environment

For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the License Compliance job to successfully run. For more information, see Offline environments.

Requirements for offline License Compliance

To use License Compliance in an offline environment, you need:

GitLab Runner with the docker or kubernetes executor.
Docker Container Registry with locally available copies of License Compliance analyzer images.

NOTE: Note: GitLab Runner has a default pull policy of always, meaning the Runner tries to pull Docker images from the GitLab container registry even if a local copy is available. GitLab Runner's pull_policy can be set to if-not-present in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to always if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines.

Make GitLab License Compliance analyzer images available inside your Docker registry

For License Compliance with all supported languages and package managers, import the following default License Compliance analyzer images from registry.gitlab.com to your offline local Docker container registry:

registry.gitlab.com/gitlab-org/security-products/license-management:latest

The process for importing Docker images into a local offline Docker registry depends on your network security policy. Please consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. Note that these scanners are updated periodically with new definitions, so consider if you are able to make periodic updates yourself.

For details on saving and transporting Docker images as a file, see Docker's documentation on docker save, docker load, docker export, and docker import.

Set License Compliance CI job variables to use local License Compliance analyzers

Add the following configuration to your .gitlab-ci.yml file. You must replace image to refer to the License Compliance Docker image hosted on your local Docker container registry:

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

license_scanning:
  image:
    name: localhost:5000/analyzers/license-management:latest

The License Compliance job should now use local copies of the License Compliance analyzers to scan your code and generate security reports, without requiring internet access.

Additional configuration may be needed for connecting to private Bower registries, private Conan registries, private Go registries, private Maven repositories, private NPM registries, private Python repositories, and private Yarn registries.

Exact name matches are required for project policies when running in an offline environment (see related issue).

Project policies for License Compliance

Introduced in GitLab Ultimate 11.4.

From the project's settings:

The list of licenses and their status can be managed.
Licenses can be manually allowed or denied.

To allow or deny a license:

Either use the Manage licenses button in the merge request widget, or navigate to the project's Settings > CI/CD and expand the License Compliance section.
Click the Add a license button.
In the License name dropdown, either:
- Select one of the available licenses. You can search for licenses in the field at the top of the list.
- Enter arbitrary text in the field at the top of the list. This will cause the text to be added as a license name to the list.
Select the Allow or Deny radio button to allow or deny respectively the selected license.

To modify an existing license:

In the License Compliance list, click the Allow/Deny dropdown to change it to the desired status.

Searching for Licenses:

Use the Search box to search for a specific license.

License Compliance report under pipelines

Introduced in GitLab Ultimate 11.2.

From your project's left sidebar, navigate to CI/CD > Pipelines and click on the pipeline ID that has a license_scanning job to see the Licenses tab with the listed licenses (if any).

License list

Introduced in GitLab Ultimate 12.7.

The License list allows you to see your project's licenses and key details about them.

In order for the licenses to appear under the license list, the following requirements must be met:

The License Compliance CI job must be configured for your project.
Your project must use at least one of the supported languages and package managers.

Once everything is set, navigate to Security & Compliance > License Compliance in your project's sidebar, and you'll see the licenses displayed, where:

Name: The name of the license.
Component: The components which have this license.
Policy Violation: The license has a license policy marked as Deny.

Policies

Introduced in GitLab Ultimate 12.9.

The Policies tab allows you to see your project's software license policies and the associated classifications for each.

Policies can be configured by maintainers of the project.

Developers of the project can view the policies configured in a project.

Troubleshooting

`ERROR -- : asdf: No preset version installed for command`

This error occurs when the version of the tools used by your project do not match the version of the pre-installed tools available in the license_scanning Docker image. The license_scanning job uses asdf-vm to activate the appropriate version of a tool that your project relies on. For example, if your project relies on a specific version of Node.js or any other supported tool you can specify the desired version by adding a .tool-versions file to the project or using the appropriate ASDF_<tool>_VERSION environment variable to activate the appropriate version.

For example, the following .tool-versions file will activate version 12.16.3 of Node.js and version 2.6.6 of Ruby.

nodejs 12.16.3
ruby 2.6.6

The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your project's .gitlab-ci.yml file.

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

license_scanning:
  variables:
    ASDF_NODEJS_VERSION: '12.16.3'
    ASDF_RUBY_VERSION: '2.6.6'

A full list of variables can be found in environment variables.

To find out what tools are pre-installed in the license_scanning Docker image use the following command:

$ docker run --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -lc 'asdf list'
golang
  1.14
gradle
  6.3
java
  adopt-openjdk-11.0.7+10
  adopt-openjdk-8u242-b08
maven
  3.6.3
nodejs
  10.20.1
  12.16.3
php
  7.4.5
python
  2.7.18
  3.8.2
ruby
  2.6.6
sbt
  1.3.8

To interact with the license_scanning runtime environment use the following command:

$ docker run -it --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -l
root@6abb70e9f193:~#

NOTE: Note: Selecting a custom version of Mono or .NET Core is currently not supported.

License Compliance (ULTIMATE)

Overview

Use cases

Supported languages and package managers

Experimental support

Requirements

Configuration

Available variables

Installing custom dependencies

Overriding the template

Configuring Maven projects

Using private Maven repos

Selecting the version of Python

Custom root certificates for Python

Using private Python repos

Configuring NPM projects

Using private NPM registries

Custom root certificates for NPM

Configuring Yarn projects

Using private Yarn registries

Custom root certificates for Yarn

Configuring Bower projects

Using private Bower registries

Custom root certificates for Bower

Configuring Conan projects

Using private Conan registries

Custom root certificates for Conan

Configuring Go projects

Using private Go registries

Custom root certificates for Go

Migration from license_management to license_scanning

Running License Compliance in an offline environment

Requirements for offline License Compliance

Make GitLab License Compliance analyzer images available inside your Docker registry

Set License Compliance CI job variables to use local License Compliance analyzers

Project policies for License Compliance

License Compliance report under pipelines

License list

Policies

Troubleshooting

ERROR -- : asdf: No preset version installed for command

Migration from `license_management` to `license_scanning`

`ERROR -- : asdf: No preset version installed for command`