How to implement FOSSA: a setup and CI-gating checklist

Who this is for

This is a hands-on implementation guide, not a sales page. It follows the path I took to put this site through FOSSA: a real repository, connected through GitHub, scanned, and gated. If you already understand software composition analysis and just want the operational steps plus the parts that are easy to miss in the UI, start here.

Prerequisites

Three things before you start:

• A FOSSA account with permission to import projects and edit organization settings.
• Access to the repository you want to scan, on a supported host (GitHub, GitLab, or Bitbucket). This guide uses GitHub.
• Admin rights on the GitHub repository. The final enforcement step is a GitHub branch-protection setting, not a FOSSA one, and only a repo or org admin can change it. This is the single most common thing teams discover too late.

Connect the repository

FOSSA imports your project straight from the version-control host, so it scans the real build graph rather than a manifest you upload. Go to Quick Import at app.fossa.com/projects/import/cloud and pick one of two GitHub integrations:

• GitHub OAuth: broader permissions, including webhooks, so scans can trigger automatically on push and pull request. The simplest path to working status checks.
• GitHub App: read-only on code and metadata, with per-repository scope. More restrictive and better for security-conscious orgs, with slightly more setup.

Authorize, choose which repositories to import (you can filter by public, private, or all, and decide whether to include forks), and FOSSA scans the default branch. No API key lands in your code, and a private repo stays private. FOSSA calls this an autobuild project: it resolves the dependency graph itself, which is why a five-dependency site can surface as several hundred packages.

Read the first scan

The first scan gives you three things worth understanding before you touch policy.

Every project and every dependency is addressed by a locator in the form fetcher+package$revision. This site imports as git+github.com/MultiOriginPartners/cloudflare-cowboy, and a specific commit appends its revision after the $. It is how FOSSA identifies the same component across thousands of projects.

Findings split into three pillars, each with its own tab on the Issue Overview page:

• Licensing: policy conflicts, policy flags, and unlicensed dependencies. On this site, 14 flagged license issues, mostly weak copyleft (LGPL-3.0 inside the sharp image library, MPL-2.0 in lightningcss) sitting three levels deep in the tree.
• Security: known vulnerabilities, ranked by severity. This site had 5, all in one direct dependency, the Astro framework.
• Quality: outdated or blocked dependencies and other operational risk. 5 here.

Each issue also carries a dependency depth. Depth 1 means the problem is in something you chose directly and can fix yourself; a deep transitive issue you usually fix by upgrading the parent that pulls it in. The Astro vulnerabilities were depth 1, which is why they were a quick win.

Set policy

Policy is where FOSSA stops being a scanner and starts being a control. You set it per project under Project Settings, Policies, or organization-wide so new projects inherit it.

• License policy: allow permissive licenses, flag or deny copyleft, and ban specific licenses outright (a "no AGPL" rule is the classic example). A flagged license becomes a policy-flag issue, exactly the 14 this site shows.
• Quality policy: deny-list packages, allow-list trusted ones, and use stale-package prevention to flag dependencies that have fallen too far behind.

At the organization level each settings group (Security, Licensing, Quality) offers Save or Propagate: save applies to one project, propagate pushes the policy down to all of them. Set policy once at the org level and you are not re-configuring every repository by hand.

Wire the CI gate (the part people get half-right)

Enforcement is split across two systems, and that is exactly where it goes wrong. Connecting FOSSA does not block any merges by itself. It takes two layers.

Layer 1, FOSSA reports. For a GitHub project, enable status checks by following the prompt on the Project Summary or Project Settings page (organization-wide, it lives under Organization Settings, Projects, GitHub Status Checks). Then, in Project Settings, Policies, enable the scan type and set the failure condition: "Fail CI/CD checks if issues matching this filter exist." Now FOSSA posts a pass or fail check onto every pull request. In the project API these appear as securityStatusCheckEnabled, licensingStatusCheckEnabled, and qualityStatusCheckEnabled set to true.

Layer 2, GitHub enforces. A red check on a pull request is just a label. On its own it does not stop anyone clicking Merge. To make it a wall, a repo admin opens GitHub, Settings, Branches, Branch protection (or a Ruleset), turns on "Require status checks to pass before merging," and marks the FOSSA checks as Required. Only then is the Merge button disabled until the checks are green.

A useful rollout: turn the checks on in warning mode first (reported but not required), clean up the existing backlog, then flip them to Required once a green build is normal. Going straight to blocking on a noisy first scan stalls everyone, which is the fastest way to get the tool turned back off.

The CLI path

The GitHub integration is the no-code path. For a monorepo, an unsupported host, or a pipeline you want full control over, the open-source fossa-cli does the same job from any CI runner. The pattern is two commands:

# 1. resolve dependencies and upload the scan
fossa analyze

# 2. fail the build if the latest scan has policy or vulnerability issues
fossa test

fossa test is the gate in CLI form: it exits 1 and prints the issues if any exist, and exits 0 when the project is clean, so any CI system can stop the pipeline on a non-zero exit. To gate only on the new problems a change introduces rather than the whole backlog, compare against a known-good revision:

fossa test --diff <revision>

The same CLI also produces a regulator-ready SBOM from the latest scan, in the format a customer asks for, which ties directly back to the SBOM work on this site:

fossa report attribution --format cyclonedx-json

Remediate the backlog

A gate is only useful if clearing it is realistic. FOSSA gives each issue three honest outcomes:

• Remediate: upgrade or remove the dependency. On this site, all 5 security issues lived in Astro, so a single framework upgrade clears every one of them at once. FOSSA marks an issue remediated automatically once the dependency moves to a safe version or is removed.
• Ignore or accept: for a flagged license you have reviewed and accepted, or a vulnerability that is not reachable in your usage, mark it ignored with a reason. It stops failing the gate but stays on the record.
• Change policy: if the gate is flagging something your team has genuinely decided is fine (a weak-copyleft license you are comfortable with), the fix is the policy, not the dependency.

The goal is not zero findings. It is that every finding has a decision attached, and that no new one slips in unreviewed.

Reports and exports

Once the data is in, FOSSA exports it for the audiences that ask. The same scan produces:

• An SBOM in SPDX or CycloneDX, for a customer or regulator.
• An attribution and notice report, the open-source license notices many licenses require you to ship.
• A machine-readable view of the project over the API, the same data the dashboard renders, which you can pull into your own tooling or a status board.

This is the back half of the SBOM lifecycle: the document is the easy part, and the reporting, gating, and monitoring around it are the actual product.

The checklist

The whole implementation, as a checklist:

• ☐ Confirm you have admin rights on the GitHub repo (needed for the final step).
• ☐ Quick Import the repo at app.fossa.com via GitHub OAuth or the GitHub App.
• ☐ Let the first scan finish, then read the Licensing, Security, and Quality tabs.
• ☐ Set license and quality policy under Project Settings, Policies, or propagate it org-wide.
• ☐ Enable GitHub status checks for the project.
• ☐ Set the failure condition: fail CI/CD checks on the issue filter you care about.
• ☐ In GitHub branch protection, mark the FOSSA checks as Required.
• ☐ Optional: add fossa analyze and fossa test to CI for non-GitHub pipelines and SBOM exports.
• ☐ Triage the first backlog: remediate, ignore with a reason, or adjust policy.
• ☐ Flip from warning to blocking once a green build is the norm.

Frequently asked questions

Keep reading

Sources

• FOSSA: Importing a project (Quick Import)
• FOSSA: GitHub integration
• FOSSA: Fail CI/CD checks
• FOSSA: Issue Overview
• FOSSA CLI cheat sheet
• GitHub: About protected branches