Jenkins

Prerequisites

Before you begin, make sure you have:

An existing Jenkins installation
A valid SCANOSS API key (required only for enterprise features)
Docker installed and available on your Jenkins agents
The following Jenkins plugins installed:
- Docker Pipeline — runs pipeline stages inside Docker containers
- Pipeline Utility Steps — provides file reading and utility functions
- Generic Webhook Trigger — enables GitHub webhook-based pipeline triggers
- Pipeline — core Jenkins pipeline support
- GitHub Plugin — GitHub repository integration

How It Works

The SCANOSS Jenkins integration runs inside your pipeline using the official SCANOSS Docker image. The integration is capable of:

Cloning a GitHub repository
Scanning the source code with the SCANOSS CLI
Checking for licence compliance and undeclared components
Generating SBOM (Software Bill of Materials) reports in multiple formats
Creating Jira issues when policy violations are found

Unlike the GitLab and GitHub Actions integrations, Jenkins does not natively post inline comments to pull requests. Instead, scan results are exposed as build artefacts and, optionally, as Jira issues when policy violations occur.

Configuration

Jenkins Credentials

Credentials should be stored in the Jenkins credentials store rather than hardcoded in your pipeline. Navigate to: Dashboard → Manage Jenkins → Credentials → (select a store) → New Credential Create the following credentials:

Credential ID	Type	Description
`scanoss-token`	Secret text	SCANOSS API key for premium/enterprise features
`gh-token`	Username/password	GitHub credentials for accessing private repositories
`jira-credentials`	Username/password	Jira username and API token for creating issues

A Jira API token is required for Jira integration. New issues are created under the account of the user associated with those credentials. Refer to the Jira documentation for details on generating a token.

Basic Pipeline Setup

The recommended approach is to load the pipeline from a Jenkinsfile stored in the root of your repository.

Step 1: Create a New Pipeline Job

From the Jenkins Dashboard, create a new Pipeline job.

Step 2: Configure the Pipeline Definition

In your pipeline job configuration, set:

Pipeline Definition: Pipeline script from SCM
SCM: Git
Repository URL: your repository URL
Credentials: your GitHub credentials (for private repositories)
Branch to build: your target branch
Script Path: Jenkinsfile

Step 3: Add the Jenkinsfile

Copy the SCANOSS Jenkins pipeline example from the integration repository to the root of your repository as Jenkinsfile.

Pipeline Parameters

All parameters are configured directly in the Jenkinsfile and can be overridden at build time via Build with Parameters.

Parameter	Description	Default
`SCANOSS_CLI_DOCKER_IMAGE`	SCANOSS CLI Docker image to use for scanning	`ghcr.io/scanoss/scanoss-py-jenkins:v1.40.1`
`ABORT_ON_POLICY_FAILURE`	Abort the pipeline on a policy violation	`false`
`SCANOSS_API_URL`	SCANOSS API endpoint	`https://api.osskb.org/scan/direct`
`SCANOSS_API_TOKEN_ID`	Jenkins credential ID referencing the SCANOSS API key	`scanoss-token`
`SKIP_SNIPPET`	Skip snippet generation	`false`
`SCANOSS_SETTINGS`	Use a SCANOSS settings file for scanning	`true`
`SETTINGS_FILE_PATH`	Path to the SCANOSS settings file	`scanoss.json`
`DEPENDENCY_ENABLED`	Enable dependency scanning	`false`
`DEPENDENCY_SCOPE`	Dependency scope to scan (`prod` or `dev`)	—
`DEPENDENCY_SCOPE_INCLUDE`	Comma-separated list of dependency scopes to include	—
`DEPENDENCY_SCOPE_EXCLUDE`	Comma-separated list of dependency scopes to exclude	—
`LICENSES_COPYLEFT_INCLUDE`	Copyleft licences to append to the default list (comma-separated)	—
`LICENSES_COPYLEFT_EXCLUDE`	Copyleft licences to remove from the default list (comma-separated)	—
`LICENSES_COPYLEFT_EXPLICIT`	Explicit list of copyleft licences to use, replacing the default (comma-separated)	—
`CREATE_JIRA_ISSUE`	Enable automatic Jira issue creation on policy violation	`false`
`JIRA_URL`	Jira instance URL	—
`JIRA_PROJECT_KEY`	Jira project key (e.g. `PROJ`)	—
`JIRA_CREDENTIALS`	Jenkins credential ID for Jira (username + API token)	`jira-credentials`
`DEBUG`	Enable debug logging	`false`

DEPENDENCY_SCOPE, DEPENDENCY_SCOPE_INCLUDE, and DEPENDENCY_SCOPE_EXCLUDE are mutually exclusive. Use DEPENDENCY_SCOPE for a single scope, or DEPENDENCY_SCOPE_INCLUDE/DEPENDENCY_SCOPE_EXCLUDE for fine-grained control.

Policy Checks

The SCANOSS Jenkins integration supports two configurable policy checks:

Copyleft (copyleftPolicyCheck) — Detects components or code snippets associated with copyleft licences. If detected, the build is marked UNSTABLE. The default copyleft licence list can be customised using the LICENSES_COPYLEFT_INCLUDE, LICENSES_COPYLEFT_EXCLUDE, or LICENSES_COPYLEFT_EXPLICIT parameters.
Undeclared (undeclaredComponentsPolicyCheck) — Compares detected components against those declared in your scanoss.json file. If undeclared components are found, the build is marked UNSTABLE.

By default, policy violations mark the build as UNSTABLE rather than FAILED. Set ABORT_ON_POLICY_FAILURE to true to fail the build outright on any policy violation.

When policy violations are detected and Jira integration is enabled, a Jira issue of type Bug is automatically created containing the full policy report and a link to the Jenkins build.

GitHub Webhook Trigger

A GitHub webhook automatically triggers the pipeline whenever code is pushed to the repository.

1. Configure Jenkins Pipeline

Navigate to Dashboard → your pipeline → Configure
In the Build Triggers section, select Generic Webhook Trigger
Copy the Jenkins webhook URL shown

2. Configure Webhook Parameters

Under Post content parameters, add:

Variable name: payload
Value: $
Expression type: JSONPath

Configure the trigger token by appending it to your Jenkins webhook URL:

http://JENKINS_URL/generic-webhook-trigger/invoke?token=YOUR_TOKEN

3. Configure GitHub

Add the Jenkins webhook URL in your GitHub repository under Settings → Webhooks. Refer to the GitHub webhook documentation for full setup instructions.

For private GitHub repositories, configure GitHub credentials in your pipeline using the gh-token credential. Refer to GitHub’s personal access token documentation for details.

Multibranch Pipeline

For repositories with multiple branches, use a Multibranch Pipeline to automatically detect and build all branches containing a Jenkinsfile.

Setup Steps

From the Jenkins Dashboard, create a new Multibranch Pipeline
Under Branch Sources, add your repository URL and credentials
Select your desired pipeline behaviours (branch discovery strategy, build triggers)
Under Build Configuration, set:
- Mode: by Jenkinsfile
- Script Path: Jenkinsfile
Apply and save

SCANOSS Policy Check Reports

SCANOSS generates policy check reports that are uploaded to the Jenkins build artefacts and, when Jira integration is enabled, attached to the corresponding Jira issue.

Default Reports

The following report is always generated for every pipeline run:

results.json — Complete raw scan results from the SCANOSS API

Conditional Reports

The following reports are generated only when their respective policy checks detect violations:

scanoss-copyleft-report.md — Generated when copyleft licences are detected
scanoss-undeclared-components-report.md — Generated when undeclared components are found

Artefacts

Scan results and policy check reports are uploaded to the Jenkins build artefacts for every run. To access them, navigate to your build in Jenkins and open the Artefacts section.

Artefact	Description
`results.json`	Raw scan results from the SCANOSS API containing detailed component and snippet match information
`scanoss-copyleft-report.md`	Copyleft policy check report in Markdown format (generated only when violations are found)
`scanoss-undeclared-components-report.md`	Undeclared components policy check report in Markdown format (generated only when violations are found)
`scanoss-cyclonedx.json`	CycloneDX 1.4 SBOM
`scanoss-spdx.json`	SPDXLite 2.2 SBOM
`scanoss-sbom.csv`	SBOM in CSV format

Documentation

Links

Prerequisites

How It Works