GitLab CI template for OSS Review Toolkit (ORT)¶

This template allows you to enforce your open-source dependencies compliance policy with OSS Review Toolkit (ORT).

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your gitlab-ci.yml:

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/ort/gitlab-ci-ort@1.0.0
    # 2: set/override component inputs²
    inputs:
      scanner-image: "ghcr.io/oss-review-toolkit/ort:latest" # ⚠ this is only an example

Use as a CI/CD template (legacy)¶

Add the following to your gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/ort'
    ref: '1.0.0'
    file: '/templates/gitlab-ci-ort.yml'

variables:
  # 2: set/override template variables
  ORT_SCANNER_IMAGE: "ghcr.io/oss-review-toolkit/ort:latest" # ⚠ this is only an example

depending on your needs and environment, you might have to use one of the template variants.

ORT scan job¶

This job performs an ORT scan of your project.

By default, the template contains three steps: analyze, advise, scan, evaluate and report bundled into one action: scan_report

The job produces a set of output files which are available to download from a pipeline console

The job is bound to the test stage, and uses the following variables:

Input / Variable	description	default value
`scanner-image` / `ORT_SCANNER_IMAGE`	The Docker image used to run `ORT`	`ghcr.io/oss-review-toolkit/ort:latest`
`ort-config-dir` / `ORT_CONFIG_DIR`	Configuration files directory (where all configuration files are located)	`.ort` (relative to the root repository directory)
`ort-source-dir` / `ORT_SOURCE_DIR`	Root directory of your project to scan with `ORT`	`.`
`auto-on-integ-and-prod-enabled` / `ORT_AUTO_ON_INTEG_AND_PROD_ENABLED`	When set to `true` , ORT analysis becomes automatic on integration and production branches (manual otherwise)	none (disabled)
`profile` / `ORT_PROFILE`	Defines the type of ORT SCAN: `BASIC` (analyse, report), `LICENSING` (analyse, scan, report), `SECURITY` (analyse, advise, report), `CUSTOM` (analyse, advise, scan, evaluate, report)	`BASIC`
`ort-scan-enabled` / `ORT_SCAN_ENABLED`	Enables `SCAN` phase. In this option the variable `ORT_PROFILE` must be set to `CUSTOM`. Set to `true` to turn it on.	`false` (disabled)
`ort-advise-enabled` / `ORT_ADVISE_ENABLED`	Enables `ADVISE` phase. In this option the variable `ORT_PROFILE` must be set to `CUSTOM`. Set to `true` to turn it on.	`false` (disabled)
`ort-evaluate-enabled` / `ORT_EVALUATE_ENABLED`	Enables `EVALUATE` phase. In this option the variable `ORT_PROFILE` must be set to `CUSTOM`. Set to `true` to turn it on.	`false` (disabled)
`advise-provider` / `ORT_ADVISE_PROVIDER`	Indicates vulnerability provider. Possible option `OssIndex`, Google `OSV`	`OSV`
`ORT_HTTP_USERNAME`	Generic username to use for HTTP(S) downloads	Empty (n/a)
/ `ORT_HTTP_PASSWORD`	Generic password to use for HTTP(S) downloads	Empty (n/a)
`mvn-settings-file` / `ORT_MVN_SETTINGS_FILE`	A path to a `settings.xml` file that allows the user to change the Maven repository	`none`
`npm-config-file` / `ORT_NPM_CONFIG_FILE`	A path to the `.npmrc` file that allows the user to change NPM settings	`none`
`npm-registry` / `ORT_NPM_REGISTRY`	A variable that contains a URL address to a custom npm repository	`none`

Basic use¶

The pipeline of the template contains basic deployment without additional configuration The basic scan of ORT will execute two agents: analyse and report. At the end of the process you fill find report files attached as the artifacts of the job This scenario will focus on the license findings basing in the declared content by the author This scenario is similar to setting the variable ORT_PROFILE: BASIC

You can build your own .ort.conf.yml file in a YAML format. The default configuration: ORT sample configuration file. The only part of the sample cofiguration file that requires modification is the section packageConfigurationProviders and packageCurationProviders. For a BASIC use the proposition is to remove or comment-out these two sections If you don't provide your custom configuration a default one will be put in place.

Advanced use¶

Licensing profile¶

You may want to extend the scanning results by in-deep analysis to search not only for declared license mentions but engage a scanning mechanism. To do so please set the variable ORT_PROFILE: LICENSING

Pipeline example:

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/ort/gitlab-ci-ort@1.0.0
    # 2: set/override component inputs²
    inputs:
      profile: "LICENSING"

Security profile¶

Another option is turning on the detection of the vulnerabilities raised for the linked artifacts, and it's version. The vulnerabilities are taken from the public databases as NVD, NIST The agent called advise uses one of the providers: OSV (Google), OssIndex , VulnerableCode (non-public)

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/ort/gitlab-ci-ort@1.0.0
    # 2: set/override component inputs²
    inputs:
      profile: "SECURITY"
      advise-provider: "OSV"

Custom profile¶

Last option is turning on the detection of all possible agents as:

scan (for deep scanning)
advise (security)
evaluate (license classification)

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/ort/gitlab-ci-ort@1.0.0
    # 2: set/override component inputs²
    inputs:
    ort-profile: "CUSTOM"
    ort-advise-provider: "OSV"
    ort-scan-enabled: true
    ort-advise-enabled: true
    ort-evaluate-enabled: true
    ort-classification-file-path: 'license-classifications.yml'
    ort-rules-file-path: 'rules.kts'

in order to use EVALUATE you need to provide two additional files as in the example above. The sample of the files:

HTTP Storage¶

Any HTTP file server can be used to store scan results. Custom headers can be configured to provide authentication credentials. For example, to use Artifactory to store scan results. Example of the config file can be found here:

ORT HTTP Storage config file

Curations YML file¶

Curations correct invalid or missing package metadata and set the concluded license for packages.

You can use the curations.yml example as the base configuration file for your scans.

Manual of ORT Curations file