GitHub Actions

Overview

The official FOSSA Action runs the FOSSA CLI inside your GitHub Actions workflow. At minimum it needs an API key. It installs the latest CLI, runs fossa analyze on your checked-out code, and can optionally gate the build with fossa test.

When to use this

This is the fastest way to get dynamic analysis from a GitHub project. It sits between the two other GitHub options:

• GitHub App / GitHub OAuth: source-host import. Minimal setup, but FOSSA runs the build itself. Best when you want managed, hands-off scanning and don't need to reproduce a real build.
• GitHub Actions (this page): minimal setup and dynamic analysis. The Action runs in your actual workflow, so FOSSA sees the real, freshly-built dependency graph (a CI/CD scan) without you hand-writing CLI install scripts.
• Generic CI: the manual equivalent if you outgrow the Action or need full control over the CLI invocation.

Prerequisites

• A FOSSA API key from Settings → Integrations → API Tokens.

  Note

  If you maintain a public repository, use a Push Only token so the key cannot be used to read sensitive data from your FOSSA account.

• A Linux or macOS runner. Windows runners are not supported. Container scanning additionally requires a running Docker daemon, which GitHub's macOS runners do not provide.

Quickstart

1. 1

   Store your API key as a secret

   In your repository, go to Settings → Secrets and variables → Actions and add a secret named FOSSA_API_KEY set to your API key. Never commit the key to source control.

2. 2

   Add the Action to a workflow

   Create or edit a workflow file (for example .github/workflows/fossa.yml). Check out your code, then add the FOSSA Action:

   YAMLCopy

   name: FOSSAon: [push, pull_request] jobs:  fossa-scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: fossas/fossa-action@main # pin to a specific version if locking is preferred        with:          api-key: ${{ secrets.FOSSA_API_KEY }}

   This runs fossa analyze and uploads a dependency snapshot to FOSSA on every push and pull request.

3. 3

   Gate the build on policy status

   Add run-tests: true to fail the build when FOSSA finds license or security issues that violate your policy. A scan must complete first, so run analysis before tests:

   YAMLCopy

         - uses: fossas/fossa-action@main        with:          api-key: ${{ secrets.FOSSA_API_KEY }}          run-tests: true

Inputs

Output: report. When generate-report is set, contains the report contents in the requested format.

Common patterns

Test only new issues on pull requests

Run fossa test against the PR base so the build fails only on issues the PR introduces, not pre-existing ones:

      - uses: fossas/fossa-action@main        with:          api-key: ${{ secrets.FOSSA_API_KEY }}          run-tests: ${{ github.event_name == 'pull_request' }}          test-diff-revision: ${{ github.event.pull_request.base.sha }}

Container scanning

Scan a built image with fossa container analyze. Replace ubuntu:20.04 with your image:

      - uses: fossas/fossa-action@main        with:          api-key: ${{ secrets.FOSSA_API_KEY }}          container: ubuntu:20.04          run-tests: true

Generate an attribution report

Capture the report from the step output and write it to a file:

      - id: fossa        uses: fossas/fossa-action@main        with:          api-key: ${{ secrets.FOSSA_API_KEY }}          run-tests: true          generate-report: html      - run: echo '${{ steps.fossa.outputs.report }}' > report.html

Upload a debug bundle

Run in debug mode and upload the resulting bundle as a build artifact for troubleshooting:

      - uses: fossas/fossa-action@main        with:          api-key: ${{ secrets.FOSSA_API_KEY }}          debug: true      - uses: actions/upload-artifact@v4        with:          name: fossa.debug.json.gz          path: ./fossa.debug.json.gz

Point at an on-premises instance

      - uses: fossas/fossa-action@main        with:          api-key: ${{ secrets.FOSSA_API_KEY }}          endpoint: fossa.my-company.com