License Compliance (ULTIMATE)
If you are using GitLab CI/CD, you can search your project dependencies for their licenses using License Compliance.
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.
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.
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.
To run a License Compliance scanning job, you need GitLab Runner with the
For GitLab 12.8 and later, to enable License Compliance, you must
that's provided as a part of your GitLab installation.
For older versions of GitLab from 11.9 to 12.7, you must
For GitLab versions earlier than 11.9, you can copy and use the job as defined
In GitLab 13.0, the
License-Management.gitlab-ci.yml template is scheduled to be removed.
Add the following to your
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.
Before GitLab 12.8, the
license_scanning job was named
In GitLab 13.0, the
license_management job is scheduled to be removed completely,
so you're advised to migrate to the
license_scanning job and used the new
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.
License Compliance can be configured using environment variables.
||no||Additional arguments for the mvn executable. If not supplied, defaults to
||no||Additional arguments for the
||no||Version of Java. If set to
||no||Version of Python. If set to
||no||Custom setup for the dependency installation. (experimental)|
||no||Base URL of Python Package Index (default:
||no||Bundle of trusted CA certificates (currently supported in Python projects).|
Installing custom dependencies
Introduced in GitLab Ultimate 11.4.
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
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
If you want to override the job definition (for example, change properties like
dependencies), you need to declare a
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
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
-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
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
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
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
file to configure trusted hosts.
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
[global] trusted-host = pypi.example.com
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.
The support of
license_management is scheduled to be dropped in GitLab 13.0.
If you're using a custom setup for License Compliance, you're required
to update your CI config accordingly:
- Change the CI template to
- Change the job name to
license_scanning(if you mention it in
- Change the artifact name to
gl-license-scanning-report.json(if you mention it in
For example, the following
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
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.
Requirements for offline License Compliance
To use License Compliance in an offline environment, you need:
- GitLab Runner with the
- Docker Container Registry with locally available copies of License Compliance analyzer images.
GitLab Runner has a default
pull policy of
meaning the runner will try 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
in an offline environment if you prefer using only locally available Docker images. However, we
recommend leaving the pull policy set to
always, as it better enables updated scanners to be used
within 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:
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.
Set License Compliance CI job variables to use local License Compliance analyzers
Override License Compliance environment variables to use to your local container registry as the source for License Compliance analyzer images.
For example, this assumes a local Docker registry repository of
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 Maven repositories.
Project policies for License Compliance
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:
Searching for Licenses:
License Compliance report under pipelines
From your project's left sidebar, navigate to CI/CD > Pipelines and click on the
pipeline ID that has a
license_management job to see the Licenses tab with the listed
licenses (if any).
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.
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.