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: 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@v6

      - name: Run SCANOSS Code Scan
        id: scanoss-code-scan-step
        uses: scanoss/gha-code-scan@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
output.filepath	Scan output file name	Optional	scanoss-raw.json
dependencies.enabled	Enable or disable scanning of dependencies	Optional	false
dependencies.scope	Gets development or production dependencies (scopes: prod - dev)	Optional	-
dependencies.scope.include	Custom list of dependency scopes to include (comma-separated)	Optional	-
dependencies.scope.exclude	Custom list of dependency scopes to exclude (comma-separated)	Optional	-
policies	Comma-separated list of active policies (copyleft/cpl, undeclared/und, depTrack/dt)	Optional	-
policies.halt_on_failure	Halt check on policy failure. If set to false checks will not fail	Optional	true
api.url	SCANOSS API URL (omit for SaaS)	Optional	https://api.osskb.org/scan/direct
api.key	SCANOSS API key	Optional	-
licenses.copyleft.include	List of Copyleft licenses to append to the default list (comma-separated)	Optional	-
licenses.copyleft.exclude	List of Copyleft licenses to remove from default list (comma-separated)	Optional	-
licenses.copyleft.explicit	Explicit list of Copyleft licenses to consider (comma-separated)	Optional	-
runtimeContainer	Runtime URL	Optional	ghcr.io/scanoss/scanoss-py:v1.45.0
skipSnippets	Skip the generation of snippets (scanFiles option must be enabled)	Optional	false
scanFiles	Enable or disable file and snippet scanning	Optional	true
scanossSettings	Settings file to use for scanning	Optional	true
settingsFilepath	Path to the SCANOSS settings file	Optional	scanoss.json
scanMode	Scan type (delta or full)	Optional	full
scanPath	Relative path within the repository to scan (e.g., src or packages/api)	Optional	.
debug	Enable debugging	Optional	false
deptrack.upload	Enable automatic upload to Dependency Track	Optional	false
deptrack.url	Dependency Track instance URL. Required when Dependency Track is enabled	Required*	-
deptrack.apikey	Dependency Track API key. Required when Dependency Track is enabled	Required*	-
deptrack.projectid	UUID of an existing project in Dependency Track. Required when project name and version are not provided	Required*	-
deptrack.projectname	Dependency Track project name (created if missing). Required when project ID is not provided	Optional	-
deptrack.projectversion	Dependency Track project version. Required when project ID is not provided	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: 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@v6
        with:
          fetch-depth: 0

      - name: Run SCANOSS Code Scan
        id: scanoss-code-scan-step
        uses: scanoss/gha-code-scan@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: 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@v6
        with:
          fetch-depth: 0 # Required for delta scans

      - name: Run SCANOSS Code Scan
        uses: scanoss/gha-code-scan@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.

Troubleshooting

gRPC errors (403) when using older action versions

Symptom: The workflow fails with 403 errors during decoration service calls (dependencies, vulnerabilities, etc.). Cause: The gRPC endpoints have been decommissioned. All API communication now goes through REST. gha-code-scan v1.5.0 and earlier shipped with scanoss-py v1.46.0, which still used gRPC for some service calls, this causes 403 errors against the current API. Fix: Update your workflow to use gha-code-scan v1.6.2 or later, which bundles scanoss-py v1.52.1 (REST-only):

uses: scanoss/code-scan-action@v1.6.2

If you need to stay on an older action version, you can override the runtime container explicitly:

uses: scanoss/code-scan-action@v1.5.0
with:
  runtimeContainer: ghcr.io/scanoss/scanoss-py:v1.52.1

Overview

License Dataset

Encryption Dataset

Security Dataset

Process & Integrations

APIs and Services

Workflows

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)

Troubleshooting

gRPC errors (403) when using older action versions

Overview

License Dataset

Encryption Dataset

Security Dataset

Process & Integrations

APIs and Services

Workflows

Documentation Index

​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)

​Troubleshooting

​gRPC errors (403) when using older action versions

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)

Troubleshooting

gRPC errors (403) when using older action versions