GitHub Actions

Prerequisites

Before you begin, make sure you have:

An existing GitHub repository
A valid SCANOSS API key

How It Works

Understanding how SCANOSS integrates with your CI/CD pipeline helps you make the most of automated code scanning and compliance checks.

CI/CD Pipeline Sequence Flow

The following diagram illustrates the complete flow when SCANOSS is integrated into your GitHub Actions workflow, including both success and failure scenarios.

Developer Day Journey

Configuration

Navigate to your GitHub repository and add the following secrets: Settings → Secrets and variables → Actions

Variable Name	Description	Value
SCANOSS_API_KEY	SCANOSS API key	xyz789…

Full Scan on Push and Pull Request

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

name: SCANOSS Full Scan

on:
  push:
    branches:
      - "main"
  pull_request:
    branches:
      - "*"

permissions:
  contents: read
  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're not using SCANOSS in SaaS mode
          # api.url: ${{ secrets.SCANOSS_URL }}

For example workflow runs, check out our GitHub Action Usage Example

Action Input Parameters

The SCANOSS GitHub Action accepts several input parameters to customise scanning behaviour.

Parameter	Description	Required	Default
policies	Comma-separated list of active policies (copyleft, undeclared, depTrack)	Optional	-
api.url	SCANOSS API URL (omit for SaaS)	Optional	https://api.osskb.org/scan/direct
api.key	SCANOSS API key	Optional	-
scanossSettings	Settings file for scanning	Optional	true
settingsFilepath	Path to the SCANOSS settings file	Optional	scanoss.json
scanMode	Scan type (delta or full)	Optional	full
deptrack.upload	Enable automatic upload to Dependency Track	Optional	false
deptrack.url	Dependency Track instance URL	Required*	-
deptrack.apikey	Dependency Track API key	Required*	-
deptrack.projectname	Dependency Track project name (created if missing)	Optional	-
deptrack.projectversion	Dependency Track project version	Optional	-

Action Output Parameters

The action produces raw scan data and metadata that can be integrated into other workflows or reporting tools.

Parameter	Description
result-filepath	Path to the generated scan results file
stdout-scan-command	Raw command output from the scanner

Policy Checks

The SCANOSS Code Scan Action supports configurable policy checks to automatically enforce compliance during CI:

Copyleft (copyleft or cpl) – Detects Copyleft-licensed components or snippets. If found, the pull request is rejected. The default Copyleft license list is defined in the SCANOSS configuration.
Undeclared (undeclared or und) – Compares detected components against those declared in the scanoss.json file (configurable via settingsFilepath). Pull requests fail if undeclared components are found.
Dependency Track (depTrack or dt) – Integrates with Dependency Track to check for vulnerabilities, license violations, and compliance. Requires deptrack.* parameters to be set.

In this setup, a standard policy runs that fails if any Copyleft licenses are detected in the scan results.

Additionally, if it is a Pull Request, a comment with a summary of the report will be automatically generated.

Delta Scan on Push and Pull Request

Scan only the changes in your pull request to quickly identify issues without needing to re-scan the entire repository.

name: SCANOSS Delta Scan

on:
  push:
    branches:
      - "main"
  pull_request:
    branches:
      - "*"

permissions:
  contents: read
  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're not using SCANOSS in SaaS mode
          # api.url: ${{ secrets.SCANOSS_URL }}

Note: A fetch-depth of 0 is required to ensure the action can access the necessary commit history to perform the delta scan correctly.

Understanding the Scan Summary

After a successful scan, GitHub Actions provides a comprehensive summary of the results. This summary offers immediate insights into the scanned files. Key details in the summary include:

Scan Report: Lists all detected licenses, policy evaluation results and the status of any configured integrations.
Downloadable Artifacts: These include SBOM files and other detailed scan data. This data can be easily downloaded and used with various compliance and vulnerability management tools.

To access the downloadable artifacts, navigate to your workflow run, locate the “Artifacts” section and click on the desired file to download it.

Simplified Dev CI/CD Pipeline Sequence Flow

For reference, here’s a streamlined view of the successful scan workflow.

Manage Components with scanoss.json

The scanoss.json file is used for managing your project’s software bill of materials (SBOM). It allows you to declare approved components, document triage decisions and customise scan behavior to enforce your organisation’s policies. This guide walks you through setting up and using scanoss.json in a GitHub Actions workflow.

Recommended .gitignore Configuration

When working with SCANOSS in your repository, we recommend the following .gitignore configuration:

# SCANOSS temporary files and cache
*.wfp
.scanoss/

Important: The scanoss.json file should be checked into Git and not added to .gitignore. This file contains your component declarations and governance decisions that should be version-controlled and shared across your team. What to ignore:

*.wfp - Winnowing fingerprint files generated during local scans
.scanoss/ - Local cache directory created by SCANOSS tools

What to commit:

scanoss.json - Your project’s SBOM declarations and scan settings

File Structure and Location

For the SCANOSS action to automatically detect it, place the scanoss.json file in the root of your repository.

your-repository/
├── .github/
│   └── workflows/
│       └── scanoss.yml
├── src/
├── .gitignore           ← Add SCANOSS exclusions here
├── scanoss.json         ← Place here and commit to Git
└── README.md

Here is an example workflow that uses scanoss.json and integrates with Dependency-Track:

name: SCANOSS Analysis with scanoss.json

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["*"]

permissions:
  contents: read
  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're not using SCANOSS in SaaS mode
          # api.url: ${{ secrets.SCANOSS_URL }}

Step-by-Step Guide to Populating scanoss.json

Follow these steps to create and manage your component declarations.

Step 1: Run an Initial Scan

First, run the workflow without a scanoss.json file. This initial scan will discover 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 a quick overview of component violations.
Download the scanoss-raw.json.zip artifact, which contains the detailed SBOM.

Step 3: Extract Component PURLs

Unzip the artifact and use a command-line tool like jq to extract a unique list of component PURLs from the scanoss-raw.json file.

# Download and unzip the artifact from the workflow run
unzip scanoss-raw.json.zip

# View the PURLs
cat scanoss-raw.json

# Example:
# pkg:github/axios/axios
# pkg:github/lodash/lodash
# pkg:npm/express@4.18.2

Tip: jq is a lightweight and flexible command-line JSON processor. It’s an essential tool for scripting and automation. If you don’t have it, you can install it from here.

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. Add comments to document why each component is approved.

{
  "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 will verify against this list.
bom.remove: Specifies components that should not be present. The scan will flag them if found.
settings.scan.ignore: Defines file or directory paths to exclude from the scan.

Step 5: Commit and Push

Add the scanoss.json file to Git and push the changes. This will trigger the workflow again.

git add scanoss.json
git commit -m "chore: Add component governance with scanoss.json"
git push

Step 6: Verify the Results

After the new workflow run completes, check the job logs for the Run SCANOSS Code Scan step. The output should now show that all components are declared and there are no undeclared components.

{
  "totalComponents": 3,
  "undeclaredComponents": 0, // ← Should be 0 after proper triage
  "declaredComponents": 3, // ← Should match total
  "totalFilesDetected": 15,
  "totalFilesUndeclared": 0,
  "totalFilesDeclared": 15
}

SBOM Export (Dependency Track)

SCANOSS GitHub Actions can be configured to automatically export your SBOM to Dependency Track for enhanced vulnerability and license management. In your workflow file .github/workflows/scanoss.yml add the Dependency Track configuration to the scanoss step.

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 on a push or pull request, go to the workflow’s Summary page and scroll to the Details section. Click More details to see the Dependency Track status. This page confirms the successful generation and upload of the SBOM to Dependency Track. If successful, you can access the project by clicking the View project in Dependency Track button.

Overview

License Dataset

Cryptography Dataset

Security Dataset

Process & Integrations

Prerequisites

How It Works

CI/CD Pipeline Sequence Flow

Developer Day Journey

Configuration

Full Scan on Push and Pull Request

Action Input Parameters

Action Output Parameters

Policy Checks

Delta Scan on Push and Pull Request

Understanding the Scan Summary

Simplified Dev CI/CD Pipeline Sequence Flow

Manage Components with scanoss.json

Recommended .gitignore Configuration

File Structure and Location

Step-by-Step Guide to Populating scanoss.json

Step 1: Run an Initial Scan

Step 2: Review Scan Results

Step 3: Extract Component PURLs

Step 4: Create Your scanoss.json File

Step 5: Commit and Push

Step 6: Verify the Results

SBOM Export (Dependency Track)

Overview

License Dataset

Cryptography Dataset

Security Dataset

Process & Integrations

​Prerequisites

​How It Works

​CI/CD Pipeline Sequence Flow

​Developer Day Journey

​Configuration

​Full Scan on Push and Pull Request

​Action Input Parameters

​Action Output Parameters

​Policy Checks

​Delta Scan on Push and Pull Request

​Understanding the Scan Summary

​Simplified Dev CI/CD Pipeline Sequence Flow

​Manage Components with scanoss.json

​Recommended .gitignore Configuration

​File Structure and Location

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

​Step 1: Run an Initial Scan

​Step 2: Review Scan Results

​Step 3: Extract Component PURLs

​Step 4: Create Your scanoss.json File

​Step 5: Commit and Push

​Step 6: Verify the Results

​SBOM Export (Dependency Track)

Prerequisites

How It Works

CI/CD Pipeline Sequence Flow

Developer Day Journey

Configuration

Full Scan on Push and Pull Request

Action Input Parameters

Action Output Parameters

Policy Checks

Delta Scan on Push and Pull Request

Understanding the Scan Summary

Simplified Dev CI/CD Pipeline Sequence Flow

Manage Components with scanoss.json

Recommended .gitignore Configuration

File Structure and Location

Step-by-Step Guide to Populating scanoss.json

Step 1: Run an Initial Scan

Step 2: Review Scan Results

Step 3: Extract Component PURLs

Step 4: Create Your scanoss.json File

Step 5: Commit and Push

Step 6: Verify the Results

SBOM Export (Dependency Track)