• Overview
• Use cases
• Supported languages and package managers
• Requirements
• Configuration
  • Available variables
  • Installing custom dependencies
  • Overriding the template
  • Configuring Maven projects
    • Using private Maven repos
  • Selecting the version of Python
  • Migration from license_management to license_scanning
• Project policies for License Compliance
• License Compliance report under pipelines
• License list
• Policies

License Compliance

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.

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.

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.

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.

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.

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.

Installing custom dependencies

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

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 that requires login credentials, you can use the MAVEN_CLI_OPTS variable to specify a custom settings.xml file.

For example, you may have a settings file like this in your project source:

<settings>
  <servers>
    <server>
      <id>my-server</id>
      <username>${private.username}</username>
      <username>${private.password}</username>
    </server>
  </servers>
</settings>

You can use this file through the following declaration in your gitlab-ci.yml file:

license_scanning:
  variables:
    MAVEN_CLI_OPTS: --settings settings.xml -Dprivate.username=foo -Dprivate.password=bar

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 2.

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

license_scanning:
  variables:
    LM_PYTHON_VERSION: 2

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

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 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

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:

1. 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.

2. Click the Add a license button.

   

3. 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.
4. Select the Allow or Deny radio button to allow or deny respectively the selected license.

To modify an existing license:

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

   

Searching for Licenses:

1. Use the Search box to search for a specific license.

   

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).

License list

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:

1. The License Compliance CI job must be configured for your project.
2. 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.

Policies

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.