Skip to main content

​
Resources

Always refer to the SCANOSS GitHub Repository for the most up-to-date version numbers and configuration parameters, as these may change with new releases.

​
Prerequisites

Before you begin, ensure you have:
  • An existing GitHub repository
  • A valid SCANOSS API key

​
How It Works

The following diagrams illustrate how SCANOSS integrates into a GitHub Actions CI/CD pipeline, covering both success and failure scenarios.

​
CI/CD Pipeline Sequence Flow

The diagram below shows the complete flow when SCANOSS is integrated into your GitHub Actions workflow, including both success and failure scenarios. developer-cicd-detailed

​
Developer Workflow Overview

The diagram below shows a typical developer workflow when using SCANOSS within a pull request cycle. developer-journey

​
Configuration

Navigate to your GitHub repository and add the following secret: Settings → Secrets and variables → Actions
Variable NameDescriptionValue
SCANOSS_API_KEYSCANOSS API keyxyz789…

​
Full Scan on Pull Requests

Create a workflow file at .github/workflows/scanoss.yml and configure it to run SCANOSS: 
name: SCANOSS Full Scan

on:
  pull_request:
    branches:
      - "*"

permissions:
  contents: write
  pull-requests: write
  checks: write
  actions: read

jobs:
  scanoss-code-scan:
    name: SCANOSS Code Scan
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run SCANOSS Code Scan
        id: scanoss-code-scan-step
        uses: scanoss/code-scan-action@v1
        with:
          scanMode: full
          api.key: ${{ secrets.SCANOSS_API_KEY }}
          # api.url — only required if you are not using the SCANOSS SaaS endpoint
          # api.url: ${{ secrets.SCANOSS_URL }}
For example workflow runs, refer to the SCANOSS Code Scan Action repository.

​
Action Input Parameters

The SCANOSS GitHub Action accepts the following input parameters to customise scanning behaviour.
ParameterDescriptionRequiredDefault
policiesComma-separated list of active policies (copyleft, undeclared, depTrack)Optional—
api.urlSCANOSS API URL. Omit when using the SaaS endpoint.Optionalhttps://api.osskb.org/scan/direct
api.keySCANOSS API keyOptional—
scanossSettingsEnable use of a settings file for scanningOptionaltrue
settingsFilepathPath to the SCANOSS settings fileOptionalscanoss.json
scanModeScan type: delta (changed files only) or full (entire repository)Optionalfull
deptrack.uploadEnable automatic upload to Dependency TrackOptionalfalse
deptrack.urlDependency Track instance URLRequired*—
deptrack.apikeyDependency Track API keyRequired*—
deptrack.projectnameDependency Track project name. Created automatically if it does not exist.Optional—
deptrack.projectversionDependency Track project versionOptional—
* Required when deptrack.upload is set to true.

​
Action Output Parameters

The action produces the following outputs, which can be referenced in subsequent workflow steps or reporting tools.
ParameterDescription
result-filepathPath to the generated scan results file
stdout-scan-commandRaw command output from the scanner

​
Policy Checks

The SCANOSS Code Scan Action supports the following configurable policy checks, which are enforced automatically during CI runs:
  • Copyleft (copyleft or cpl) — Detects components or code snippets under copyleft licences. If any are found, the pull request is rejected. The set of copyleft licences evaluated is defined in the SCANOSS configuration.
  • Undeclared (undeclared or und) — Compares detected components against those declared in scanoss.json (configurable via settingsFilepath). Pull requests fail if undeclared components are found.
  • Dependency Track (depTrack or dt) — Integrates with Dependency Track to check for vulnerabilities, licence violations, and compliance issues. Requires all deptrack.* parameters to be configured.
When the copyleft policy is enabled, the workflow will fail if any copyleft-licensed components are detected in the scan results. classic-policy For pull request triggers, a comment containing a summary of the scan report is automatically posted to the pull request. scanoss-pr

​
Delta Scan on Pull Requests

Use delta scan mode to scan only the files changed in a pull request. This avoids re-scanning the entire repository on each run. 
name: SCANOSS Delta Scan

on:
  pull_request:
    branches:
      - "*"

permissions:
  contents: write
  pull-requests: write
  checks: write
  actions: read

jobs:
  scanoss-code-scan:
    name: SCANOSS Code Scan
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run SCANOSS Code Scan
        id: scanoss-code-scan-step
        uses: scanoss/code-scan-action@v1
        with:
          scanMode: delta
          api.key: ${{ secrets.SCANOSS_API_KEY }}
          # api.url — only required if you are not using the SCANOSS SaaS endpoint
          # api.url: ${{ secrets.SCANOSS_URL }}
Note: Setting fetch-depth: 0 is required. Without the full commit history, the action cannot determine which files have changed and the delta scan will not function correctly.

​
Understanding the Scan Summary

After a successful scan, GitHub Actions displays a summary of the results in the workflow run view. The summary includes:
  • Scan Report — Lists all detected licences, policy evaluation results, and the status of any configured integrations.
  • Downloadable Artefacts — Includes SBOM files and detailed scan data. These can be used with external compliance and vulnerability management tools.
To download artefacts, navigate to your workflow run, locate the Artefacts section, and click the file you wish to download. artifacts-gha

​
Simplified CI/CD Pipeline Sequence Flow

The diagram below shows a streamlined view of the workflow for a successful scan. developer-cicd

​
Managing Components with scanoss.json

The scanoss.json file manages your project’s Software Bill of Materials (SBOM). It allows you to declare approved components, record triage decisions, and customise scan behaviour to enforce your organisation’s policies. This section covers how to set up and use scanoss.json in a GitHub Actions workflow. When working with SCANOSS in your repository, add the following entries to your .gitignore: 
# SCANOSS temporary files and cache
*.wfp
.scanoss/
Important: The scanoss.json file must be committed to Git and must not be added to .gitignore. It contains your component declarations and governance decisions, which should be version-controlled and shared across your team. Exclude from Git:
  • *.wfp — Winnowing fingerprint files generated during local scans
  • .scanoss/ — Local cache directory created by SCANOSS tools
Commit to Git:
  • scanoss.json — Your project’s SBOM declarations and scan settings

​
File Structure and Location

Place scanoss.json in the root of your repository so that the SCANOSS action can detect it automatically. 
your-repository/
├── .github/
│   └── workflows/
│       └── scanoss.yml
├── src/
├── .gitignore           ← Add SCANOSS exclusions here
├── scanoss.json         ← Place here and commit to Git
└── README.md
The following example workflow uses scanoss.json and integrates with Dependency Track: 
name: SCANOSS Analysis with scanoss.json

on:
  pull_request:
    branches:
      - "*"

permissions:
  contents: write
  pull-requests: write
  checks: write
  actions: read

jobs:
  scanoss-code-scan:
    name: SCANOSS Code Scan
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for delta scans

      - name: Run SCANOSS Code Scan
        uses: scanoss/code-scan-action@v1
        with:
          # Scan mode for PRs/pushes
          scanMode: delta

          # Enable and specify the settings file
          scanossSettings: true
          settingsFilepath: scanoss.json

          # Enforce policies for undeclared components and Dependency Track
          policies: undeclared, dt
          policies.halt_on_failure: false # Set to true to fail the build on violations

          # Dependency Track integration
          deptrack.upload: true
          deptrack.url: ${{ secrets.DT_SERVER_URL }}
          deptrack.apikey: ${{ secrets.DT_API_KEY }}
          deptrack.projectname: "my-project"
          deptrack.projectversion: "PR-${{ github.event.pull_request.number }}"

          # SCANOSS API credentials
          api.key: ${{ secrets.SCANOSS_API_KEY }}
          # api.url — only required if you are not using the SCANOSS SaaS endpoint
          # api.url: ${{ secrets.SCANOSS_URL }}

​
Step-by-Step Guide to Populating scanoss.json

Follow these steps to create and populate your component declarations.

​
Step 1: Run an Initial Scan

Run the workflow without a scanoss.json file. The initial scan will identify all components present in your repository and report them as undeclared. 
# Commit and push your code to trigger the workflow
git push

​
Step 2: Review Scan Results

Once the workflow completes, navigate to the run in the Actions tab of your repository.
  • Review the Annotations on the summary page for an overview of component violations.
  • Download the scanoss-raw.json.zip artefact, which contains the detailed SBOM data.

​
Step 3: Extract Component PURLs

Unzip the artefact and use a command-line tool such as jq to extract a unique list of Package URLs (PURLs) from the scanoss-raw.json file. 
# Download and unzip the artefact from the workflow run
unzip scanoss-raw.json.zip

# View the PURLs
cat scanoss-raw.json

# Example output:
# pkg:github/axios/axios
# pkg:github/lodash/lodash
# pkg:npm/express@4.18.2
Tip: jq is a command-line JSON processor useful for scripting and automation. Installation instructions are available at jqlang.github.io/jq.

​
Step 4: Create Your scanoss.json File

Create a scanoss.json file in your repository root. Use the PURLs from the previous step to populate the bom.include section. Include comments to record the approval rationale for each component. 
{
  "bom": {
    "include": [
      {
        "purl": "pkg:github/lodash/lodash",
        "comment": "Utility library — approved by Tech Lead on 2024-12-10"
      },
      {
        "purl": "pkg:github/axios/axios",
        "comment": "HTTP client — approved for API communication"
      }
    ],
    "remove": [
      {
        "purl": "pkg:npm/express@4.17.1",
        "comment": "Old version with known vulnerabilities. Upgrade to 4.18.2+."
      }
    ]
  },
  "settings": {
    "scan": {
      "ignore": ["**/test/**", "**/node_modules/**", "**/dist/**"]
    }
  }
}
  • bom.include — Lists all approved components. The scan validates detected components against this list.
  • bom.remove — Specifies components that must not be present. The scan will flag any matches.
  • settings.scan.ignore — Defines file or directory paths to exclude from the scan.

​
Step 5: Commit and Push

Add scanoss.json to Git and push. This will trigger the workflow. 
git add scanoss.json
git commit -m "chore: Add component governance with scanoss.json"
git push

​
Step 6: Verify the Results

After the workflow run completes, check the job logs for the Run SCANOSS Code Scan step. The output should confirm that all components are declared and no undeclared components remain. 
{
  "totalComponents": 3,
  "undeclaredComponents": 0, // ← Should be 0 after triage
  "declaredComponents": 3, // ← Should match totalComponents
  "totalFilesDetected": 15,
  "totalFilesUndeclared": 0,
  "totalFilesDeclared": 15
}

​
SBOM Export to Dependency Track

The SCANOSS GitHub Action can be configured to automatically export your SBOM to Dependency Track for vulnerability and licence management. Add the following Dependency Track configuration to the SCANOSS step in your workflow file (.github/workflows/scanoss.yml): 
with:
  policies: dt
  scanMode: full
  deptrack.upload: true
  deptrack.url: ${{ secrets.DT_SERVER_URL }}
  deptrack.apikey: ${{ secrets.DT_API_KEY }}
  deptrack.projectname: "my-project"
  deptrack.projectversion: "1.0.0"
  api.url: ${{ secrets.SCANOSS_URL }}
  api.key: ${{ secrets.SCANOSS_API_KEY }}
After the workflow completes, navigate to the workflow’s Summary page and scroll to the Details section. Click More details to view the Dependency Track upload status. If the upload was successful, click View project in Dependency Track to open the project directly. dt-step