Documentation Index
Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
Before you begin, make sure you have:
- An existing Jenkins installation
- A valid SCANOSS API key (required only for enterprise features)
- 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
Configuration
Jenkins Credentials
Credentials should be stored in the Jenkins credentials store rather than hardcoded in your pipeline. Navigate to:
Dashboard → Manage Jenkins → Credentials → (global) → Add Credentials
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 |
Use the exact credential IDs shown above — they are referenced by name in the Jenkinsfile.
Pipeline Setup
Step 1: Create a New Pipeline Job
- Open the Jenkins Dashboard
- Click New Item
- Enter a job name (e.g.
scanoss-scan)
- Select Pipeline as the job type
- Click OK to create the job
- Navigate to the Pipeline section in the job configuration
- Set Definition to
Pipeline script from SCM
- Select Git as the SCM
- Enter the repository URL (e.g.
https://github.com/your-org/your-repo)
- Set Credentials:
- none - for public repositoriesgh-token for private repositories
- Set Branch Specifier to
*/main (or */master depending on your default branch)
- Set Script Path to
Jenkinsfile
- Click Save to apply the configuration
Step 3: Add the Jenkinsfile
Copy the SCANOSS Jenkins pipeline from the official integration repository and save it as Jenkinsfile (no extension) in the root of your repository.
Step 4: Run the Pipeline
- Go to the pipeline job page in Jenkins
- Click Build Now to start a new build
- Open Build History and select the latest build number
- Click Console Output to monitor the scan execution in real time
Step 5: Review the Results
After the build completes, click Artifacts in the build to access the scan results:
| File | Description |
|---|
results.json | Raw scan results from the SCANOSS API |
scanoss-copyleft-report.md | Copyleft licence violations (generated only when violations are found) |
scanoss-undeclared-components-report.md | Undeclared open source components (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 |
Step 6: (Optional) Set Up GitHub Webhook Auto-Trigger
To automatically trigger the pipeline on every push to GitHub:
In Jenkins:
- Go to your pipeline → Configure → Build Triggers
- Check Generic Webhook Trigger
- Under Post content parameters, add:
- Variable:
payload
- Value:
$
- Expression type:
JSONPath
- Note your webhook URL:
http://YOUR_JENKINS_URL/generic-webhook-trigger/invoke?token=YOUR_TOKEN
In GitHub:
- Go to your repo → Settings → Webhooks → Add webhook
- Paste the Jenkins webhook URL
- Set content type to
application/json
- Click Add webhook
For detailed webhook setup instructions, refer to the GitHub webhook documentation.
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
Private GitHub Integration
For private repositories, authentication is required. Configure appropriate credentials (such as a personal access token) in Jenkins.
Refer to the GitHub documentation for guidance on creating and managing tokens.
Pipeline Parameters
All parameters are configured directly in the Jenkinsfile and can be overridden at build time via Build with Parameters.
| Parameter | Description | Default | Type |
|---|
| SCANOSS_CLI_DOCKER_IMAGE | SCANOSS CLI Docker Image. | https://ghcr.io/scanoss/scanoss-py-jenkins:v1.46.0 | Pipeline |
| ABORT_ON_POLICY_FAILURE | Abort pipeline on pipeline failure. | false | Pipeline |
| SCANOSS_API_URL | SCANOSS API endpoint. | https://api.osskb.org/scan/direct | Pipeline |
| SCANOSS_API_TOKEN_ID | SCANOSS API Token ID. | scanoss-token | Pipeline |
| SCAN_PATH | Relative path within the repository to scan (e.g., src or packages/api). Must be relative, no parent directory references (..) allowed. | . | Pipeline |
| SKIP_SNIPPET | Skip the generation of snippets. | false | Pipeline |
| SCANOSS_SETTINGS | Settings file to use for scanning. See the SCANOSS settings documentation | true | Pipeline |
| SETTINGS_FILE_PATH | SCANOSS settings file path. | scanoss.json | Pipeline |
| DEPENDENCY_ENABLED | Scan dependencies (optional - default false). | false | Pipeline |
| DEPENDENCY_SCOPE | Gets development or production dependencies (scopes: ‘prod’ - ‘dev’). | ” | Pipeline |
| DEPENDENCY_SCOPE_INCLUDE | Custom list of dependency scopes to be included. Provide scopes as a comma-separated list. | ” | Pipeline |
| DEPENDENCY_SCOPE_EXCLUDE | Custom list of dependency scopes to be EXCLUDED. Provide scopes as a comma-separated list. | ” | Pipeline |
| LICENSES_COPYLEFT_INCLUDE | List of Copyleft licenses to append to the default list. Provide licenses as a comma-separated list. | ” | Pipeline |
| LICENSES_COPYLEFT_EXCLUDE | List of Copyleft licenses to remove from default list. Provide licenses as a comma-separated list. | ” | Pipeline |
| LICENSES_COPYLEFT_EXPLICIT | Explicit list of Copyleft licenses to consider. Provide licenses as a comma-separated list. | ” | Pipeline |
| CREATE_JIRA_ISSUE | Enables JIRA reporting | false | Pipeline |
| JIRA_URL | JIRA URL | ” | Pipeline |
| JIRA_PROJECT_KEY | JIRA Project Key | ” | Pipeline |
| JIRA_CREDENTIALS | JIRA credentials ID | jira-credentials | Pipeline |
Policy Checks
The SCANOSS Jenkins integration includes two built-in policies designed to enforce compliance and improve visibility into open source usage:
-
Copyleft
This policy detects components or code snippets associated with copyleft licenses. If any such licenses are identified, the pull request (PR) is automatically rejected. The default list of copyleft licenses is defined in the following file, and can be reviewed or extended as needed.
-
Undeclared
This policy compares detected components in the repository against those declared in the scanoss.json file (the path can be customized via configuration). If any components are found that are not declared, the pipeline fails, ensuring full dependency transparency.
JIRA Integration
When policy checks fail and JIRA integration is configured, issues are automatically created to track and remediate violations.
To enable this functionality, you must provide valid JIRA credentials. Issues will be created on behalf of the configured user.
An API token is required for authentication. For more details on generating and managing tokens, refer to the JIRA documentation.
