Configuration

​

Prerequisites

• A running Dependency Track instance (self-hosted or cloud)
• A GitHub repository with GitHub Actions enabled
• A Dependency Track API key (from Administration → Access Management → Teams → API Keys)
• The base URL for your Dependency Track instance
• A SCANOSS API key

​

GitHub Secrets Configuration

​

Navigate to Repository Secrets

1. Go to your GitHub repository.
2. Click Settings → Secrets and variables → Actions.
3. Click New repository secret.

​

Add Required Secrets

​

GitHub Actions Workflow

​

Create Workflow Directory

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

​

Create Workflow File

name: SCANOSS with Dependency Track

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:
          policies: copyleft, undeclared, dt
          scanMode: "full"
          dependencies.enabled: true
          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.key: ${{ secrets.SCANOSS_API_KEY }}
          # api.url — required only if not using SCANOSS in SaaS mode
          # api.url: ${{ secrets.SCANOSS_URL }}

      - name: Print scan command
        # Outputs the CLI command used to invoke the scan, useful for debugging
        run: echo "${{ steps.scanoss-code-scan-step.outputs.stdout-scan-command }}"

      - name: Print results
        run: cat "${{ steps.scanoss-code-scan-step.outputs.result-filepath }}"

​

Workflow Configuration Options

​

Event Triggers

• Push to main branch: Triggers on commits to the main branch.
• Pull requests: Triggers on all pull requests targeting any branch.

on:
  push:
    branches:
      - "main"
      - "develop"
  pull_request:
    branches:
      - "main"
  schedule:
    - cron: "0 0 * * 0" # Weekly on Sunday at midnight

​

Permissions

​

SCANOSS Code Scan Action Parameters

* Note: These parameters are required when deptrack.upload is set to true.

​

Customising Project Information

deptrack.projectname: "your-project-name"
deptrack.projectversion: "1.0.0"

deptrack.projectname: "${{ github.repository }}"
deptrack.projectversion: "${{ github.ref_name }}"

​

Commit and Push Workflow

# Stage the workflow file
git add .github/workflows/scanoss-monitoring.yml

# Commit the workflow
git commit -m "Add SCANOSS continuous monitoring workflow"

# Push to your repository
git push origin main

​

Monitoring Workflow Execution

​

View Workflow Runs

1. Go to your GitHub repository.
2. Click the Actions tab.
3. Select the SCANOSS with Dependency Track workflow.
4. View the list of workflow runs.

​

Workflow Execution Steps

1. Checkout code — Clones the repository into the runner environment.
2. Run SCANOSS Code Scan — Executes the scan and uploads results to Dependency Track.
3. Print scan command — Outputs the CLI command used during the scan, useful for debugging.
4. Print results — Outputs the raw scan results to the workflow log.

​

Understanding the Pipeline Summary

​

Scan Report

• Pie chart visualisation of licence distribution
• Detailed table showing each licence name
• Copyleft indicators
• Reference URLs for licence information

​

Policies

• Copyleft policy results
• Undeclared components policy results
• Dependency Track policy results
• Option to expand each policy for further detail

​

Details

• Confirmation that scan results were uploaded to Dependency Track
• Direct link to the project in Dependency Track
• Upload timestamp and status

​

Annotations

• Errors, warnings, or notices generated during the run
• Context for issues such as failed pull request comments
• Flagged code snippets or components

​

Artefacts

• Scan reports
• Policy results
• SBOM exports (CycloneDX, SPDX)
• All artefacts are available for download for further review

​

Accessing Dependency Track

​

Open Your Project

1. Go to the workflow run summary.
2. Find the Details section.
3. Click the View Project link.

​

Dashboard Overview

• Components: Full inventory of components with licences, versions, and risk scores.
• Dependency Graph: Visual representation of dependency relationships.
• Audit Vulnerabilities: Security vulnerabilities identified and requiring attention.
• Policy Violations: Active policy breaches requiring review.

​

Troubleshooting

​

Common Issues

​

Workflow Fails with Authentication Error

• Verify that your API keys are correct.
• Check that secrets are properly configured in GitHub.
• Ensure the Dependency Track team has the required API access permissions.

​

SBOM Upload Fails

• Verify that DT_SERVER_URL is correct and reachable from GitHub Actions.
• Check that your Dependency Track instance is running.
• Ensure that firewall rules permit inbound connections from GitHub Actions.
• Verify that the API key has project creation permissions.

​

Scan Results Not Appearing

• Confirm that deptrack.upload: true is set in your workflow configuration.
• Verify that the project name and version are correct.
• Review Dependency Track logs for import errors.
• Confirm that the SBOM format is supported (CycloneDX or SPDX).

​

Debug Mode

- name: Run SCANOSS Code Scan
  id: scanoss-code-scan-step
  uses: scanoss/code-scan-action@v1
  with:
    # ... other parameters ...
    debug: true