License compliance (ULTIMATE)

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.

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

You can select a license to see more information.

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.

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.

1. Gradle 7 and later is not supported as dependencies are not discovered when included with the implementation directive. Please see GitLab#341222 for more details.

Experimental support

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

Enable License Compliance

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

• Enable Auto License Compliance (provided by Auto DevOps).
• Include the License-Scanning.gitlab-ci.yml template in your .gitlab-ci.yml file.

Please note that License Compliance is not supported when GitLab is run with FIPS mode enabled.

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.
• FIPS mode must be disabled.

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.

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.

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

For example:

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

variables:
  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.

Working with Monorepos

Depending on your language, you may need to specify the path to the individual projects of a monorepo using the LICENSE_FINDER_CLI_OPTS variable. Passing in the project paths can significantly speed up builds over using the --recursive license_finder option.

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

variables:
  LICENSE_FINDER_CLI_OPTS: "--aggregate_paths=relative-path/to/sub-project/one relative-path/to/sub-project/two"

Overriding the template

WARNING: 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: Security/License-Scanning.gitlab-ci.yml

license_scanning:
  variables:
    CI_DEBUG_TRACE: "true"

Configuring Maven projects

The License Compliance tool provides a MAVEN_CLI_OPTS CI/CD 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: Security/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 repositories

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

Read more on how to use private Maven repositories.

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: Security/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 Java

License Compliance uses Java 8 by default. You can specify a different Java version using LM_JAVA_VERSION.

LM_JAVA_VERSION only accepts versions: 8, 11, 14, 15.

Selecting the version of Python

• Introduced in GitLab 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 CI/CD variable to 2.

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

license_scanning:
  variables:
    LM_PYTHON_VERSION: 2

LM_PYTHON_VERSION or ASDF_PYTHON_VERSION can be used to specify the desired version of Python. When both variables are specified LM_PYTHON_VERSION takes precedence.

Custom root certificates for Python

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

Using private Python repositories

If you have a private Python repository you can use the PIP_INDEX_URL CI/CD variable to specify its location.

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 CI/CD 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 CI/CD 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 CI/CD variable, or by specifying a ca setting in a .bowerrc file.

Configuring Bundler projects

Using private Bundler registries

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

For example:

source "https://gems.example.com"

Custom root certificates for Bundler

You can supply a custom root certificate to complete TLS verification by using the ADDITIONAL_CA_CERT_BUNDLE CI/CD variable, or by specifying a BUNDLE_SSL_CA_CERT variable in the job definition.

Configuring Cargo projects

Using private Cargo registries

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

For example:

[registries]
my-registry = { index = "https://my-intranet:8080/git/index" }

Custom root certificates for Cargo

To supply a custom root certificate to complete TLS verification, do one of the following:

• Use the ADDITIONAL_CA_CERT_BUNDLE CI/CD variable.
• Specify a CARGO_HTTP_CAINFO variable in the job definition.

Configuring Composer projects

Using private Composer registries

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

For example:

{
  "repositories": [
    { "packagist.org": false },
    {
      "type": "composer",
      "url": "https://composer.example.com"
    }
  ],
  "require": {
    "monolog/monolog": "1.0.*"
  }
}

Custom root certificates for Composer

You can supply a custom root certificate to complete TLS verification by using the ADDITIONAL_CA_CERT_BUNDLE CI/CD variable, or by specifying a COMPOSER_CAFILE variable in the job definition.

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: 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 CI/CD 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 CI/CD 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 CI/CD 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: Security/License-Scanning.gitlab-ci.yml

license_scanning:
  variables:
    GOFLAGS: '-insecure'

Using private NuGet registries

If you have a private NuGet registry you can add it as a source by adding it to the packageSources section of a nuget.config file.

For example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="custom" value="https://nuget.example.com/v3/index.json" />
  </packageSources>
</configuration>

Custom root certificates for NuGet

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

Migration from license_management to license_scanning

WARNING: The license_management job was deprecated in GitLab 12.8. The License-Management.gitlab-ci.yml template was removed from GitLab 14.0.

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 configuration accordingly:

1. Change the CI template to License-Scanning.gitlab-ci.yml.
2. Change the job name to license_scanning (if you mention it in .gitlab-ci.yml).
3. Change the artifact name to license_scanning, and the filename 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: Security/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:

• To meet the standard License Compliance prerequisites.
• Docker Container Registry with locally available copies of License Compliance analyzer images.

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. The GitLab Runner 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/security-products/license-finder: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/CD 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: Security/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 registries for:

• Bower,
• Bundler,
• Conan,
• Go,
• Maven repositories,
• npm,
• Python repositories,
• Yarn.

SPDX license list name matching

Introduced in GitLab 13.3.

Prior to GitLab 13.3, offline environments required an exact name match for project policies. In GitLab 13.3 and later, GitLab matches the name of project policies with identifiers from the SPDX license list. A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab instance's administrator can manually update it with a Rake task.

License list

Introduced in GitLab 12.7.

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

For the licenses to appear under the license list, the following requirements must be met:

1. The License Compliance CI/CD job must be enabled for your project.
2. Your project must use at least one of the supported languages and package managers.

When everything is configured, on the left sidebar, select Security & Compliance > License Compliance.

The licenses are 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 12.9.

Policies allow you to specify licenses that are allowed or denied in a project. If a denied license is newly committed it blocks the merge request and instructs the developer to remove it. Note, the merge request is not able to be merged until the denied license is removed. You may add a License-Check approval rule, which enables a designated approver that can approve and then merge a merge request with denied license.

The Policies tab in the project's license compliance section displays your project's license policies. Project maintainers can specify policies in this section.

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

Enabling License Approvals within a project

Introduced in GitLab 12.3.

Prerequisites:

• Maintainer or Owner role.

License-Check is a merge request approval rule you can enable to allow an individual or group to approve a merge request that contains a denied license.

You can enable License-Check one of two ways:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > General.
3. Expand Merge request approvals.
4. Select Enable or Edit.
5. Add or change the Rule name to License-Check (case sensitive).

• Create an approval group in the project policies section for License Compliance. You must set this approval group's number of approvals required to greater than zero. Once you enable this group in your project, the approval rule is enabled for all merge requests.

Any code changes cause the approvals required to reset.

An approval is required when a license report:

• Contains a dependency that includes a software license that is denied.
• Is not generated during pipeline execution.

An approval is optional when a license report:

• Contains no software license violations.
• Contains only new licenses that are allowed or unknown.

Warnings

We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes.

Troubleshooting

ASDF_PYTHON_VERSION does not automatically install the version

Defining a non-latest Python version in ASDF_PYTHON_VERSION doesn't have it automatically installed. If your project requires a non-latest version of Python:

1. Define the required version by setting the ASDF_PYTHON_VERSION CI/CD variable.
2. Pass a custom script to the SETUP_CMD CI/CD variable to install the required version and dependencies.

For example:

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

license_scanning:
    SETUP_CMD: ./setup.sh
    ASDF_PYTHON_VERSION: "3.7.2"
  before_script:
    - echo "asdf install python 3.7.2 && pip install -r requirements.txt" > setup.sh
    - chmod +x setup.sh
    - apt-get -y update
    - apt-get -y install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

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 activates version 12.16.3 of Node.js and version 2.7.4 of Ruby.

nodejs 12.16.3
ruby 2.7.4

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

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

license_scanning:
  variables:
    ASDF_NODEJS_VERSION: '12.16.3'
    ASDF_RUBY_VERSION: '2.7.4'

A full list of variables can be found in CI/CD 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/security-products/license-finder:4 /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/security-products/license-finder:4 /bin/bash -l
root@6abb70e9f193:~#

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