CI/CD Integration

This guide walks you through integrating SCANOSS into your CI/CD pipeline. You’ll learn how to automate scans, configure compliance policies and generate SBOMs as part of your continuous integration workflow.

Prerequisites

Before you begin, ensure you have:

• GitHub repository with your project
• (Optional) SCANOSS API key for enterprise features

If you haven’t completed the Local Testing guide yet, we recommend starting there to understand how SCANOSS scanning works before automating it in CI/CD.

Setup GitHub Actions Workflow

GitHub Actions provides automated workflows that run on specific events like pushes and pull requests. We’ll create a workflow that scans your code with SCANOSS on every change.

Create a Feature Branch

Open your project in your IDE (for example, VS Code), then open the terminal in your project folder. Make sure your project is initialised with Git.

Run this command to create a new branch for the workflow:

git checkout -b add-scanoss-workflow

Create Workflow Directory

GitHub Actions expects workflow files to be stored in a specific location within your project.

In the root of your project, create a folder named .github, and inside it, create another folder called workflows.

your-project/
└── .github/
    └── workflows/

Create the Workflow File

Create a file named scanoss.yml in the .github/workflows directory with the following configuration:

name: SCANOSS Scan

on:
  pull_request:
    branches: [main]

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

jobs:
  scanoss-scan:
    runs-on: ubuntu-latest

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

      - name: Run SCANOSS Code Scan
        uses: scanoss/code-scan-action@v1
        with:
          scanMode: full
          policies: undeclared,copyleft
          api.key: ${{ secrets.SCANOSS_API_KEY }}

This workflow:

• Runs on pull requests to the main branch
• Performs a full scan of your repository
• Enforces undeclared and copyleft policies
• Requires a SCANOSS API key (stored as a secret)

Understanding Workflow Triggers

The workflow file above uses on: pull_request: branches: [main] to determine when SCANOSS runs. GitHub Actions workflows can be triggered by various events:

Recommended for getting started - Run on pull requests to main:

on:
  pull_request:
    branches: [main]

Other common options:

• On push to specific branches: push: branches: [main, develop]
• On both push and pull requests: Combine both triggers
• Manual trigger: Add workflow_dispatch: to run manually from GitHub UI
• Scheduled: Use schedule: with cron syntax for periodic scans

You can always modify triggers later as your workflow evolves.

Understanding Compliance Policies

The workflow file uses policies: undeclared,copyleft to enforce compliance rules. SCANOSS can enforce these policies to fail your workflow when issues are detected:

• undeclared - Fails if open source components aren’t declared in scanoss.json
• copyleft - Fails if copyleft-licensed components are detected

If you completed Local Testing, you should already have a scanoss.json file that declares your components.

Configure API Secrets

Your SCANOSS API key should never be hardcoded in your workflow files. Instead, store it securely as a GitHub secret.

Add SCANOSS API Key

1. Go to your GitHub repository
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret
4. Set the following:
   • Name: SCANOSS_API_KEY
   • Secret: Your SCANOSS API key
5. Click Add secret

If you don’t have a SCANOSS API key, you can remove the api.key parameter from the workflow. The action will use the public API.

Trigger Your First Workflow Run

Now that you’ve created your workflow file, let’s commit it and trigger the first scan.

Commit and Push Your Changes

Open your terminal and execute the following commands in order:

1. Stage your workflow file:

   git add .github/workflows/scanoss.yml
   

2. Commit the workflow:

   git commit -m "Add SCANOSS workflow"
   

3. Update your branch with latest main:

   git pull origin main --rebase
   

4. Push your branch to GitHub:

   git push origin add-scanoss-workflow
   

Create a Pull Request

1. Go to your GitHub repository
2. You should see a prompt to “Compare & pull request” for your branch
3. Click “Compare & pull request”
4. Review the changes and click “Create pull request”

Monitor the Workflow Execution

Once you create the pull request, GitHub Actions will automatically trigger your workflow:

1. In your pull request, click the “Checks” tab
2. You should see your “SCANOSS Scan” workflow running
3. Click on the workflow to see real-time progress
4. Wait for the workflow to complete

Review Scan Results

After the workflow completes its run, navigate to the Summary page to view detailed scan results.

License Distribution

At the top of the Summary page, you’ll find a license pie chart showing the distribution of licenses detected in your project.

Below the chart, a detailed table lists each license along with the components associated with it.

Policy Compliance

The Policies section shows the outcome of each configured policy check.

In this example:

• Undeclared Policy: Failed (some components are not declared).

• Copyleft Policy: Failed (copyleft-licensed components detected).

• Dependency Track: Failed

Status Checks

The Details section provides the status of optional integrations, such as Dependency Track, giving additional insight into the scan run.

Artifacts

At the bottom of the Summary page, you’ll find the Artifacts section showing all files produced during the workflow run:

Click any artifact name to download it directly.

For complete guidance on configuring SCANOSS with GitHub Actions, refer to the documentation.

Need help? Contact our AI assistant