CI/CD Scanning

Provide dependency data from your existing CI/CD environment for faster, more accurate FOSSA scans.

4 min readUpdated Jul 9, 2026

Overview

CI/CD scanning is the preferred integration model when you already have a working build environment. Instead of FOSSA running its own build of your code, you install the FOSSA CLI into your existing CI pipeline and upload dependency data directly. FOSSA receives a perfect replica of your build's actual dependency graph, no guessing, no false positives.

Once a project has been uploaded via fossa analyze, it becomes a provided build project. FOSSA no longer runs automated builds on it; updates are driven entirely by how often your CI runs and uploads new results.

Why use CI/CD scanning

Advantages:

Matches your exact build behavior, no unused test or dev dependencies in results
Works with large, complex builds that are hard to replicate in FOSSA's environment
No code access required; FOSSA never clones or scans your source
Higher priority processing, so results arrive faster

Trade-offs:

FOSSA cannot trigger a new dependency analysis from the UI; a new CI run is required. You can still run a policy scan from the UI to re-evaluate existing dependency data against updated policies
Requires the FOSSA CLI to be added to your build pipeline

Quickstart

1
Install the FOSSA CLI
Follow the CLI installation guide to install fossa on your CI machine or developer workstation.
2
Analyze your project
Run the following after a successful build:
Shell
FOSSA_API_KEY=<your_api_key> fossa analyze
This uploads your project's dependency graph to FOSSA. Run it after the build completes so that the full dependency tree is captured. Analysis runs asynchronously. You can continue with tests while it processes.
3
Check for issues
Shell
fossa test
Blocks until analysis is complete, then fails the build if any license or security issues are found. Run this after your tests.

Integrating into CI

The typical fully-integrated CI workflow:

Revision is pushed to your Git host
CI clones the repository and runs the build
Build succeeds and produces a production artifact
fossa analyze runs and uploads the dependency graph
CI runs tests; fossa test checks for FOSSA issues and fails the build if any are found
If all checks pass, the revision is deployed or merged

For platform-specific setup, see the integrations guides (including GitHub Actions, Jenkins, GitLab, and CircleCI) or Generic CI for any other system.

Note

For security, pass FOSSA_API_KEY as an environment variable rather than storing it in .fossa.yml.

Configuration

For projects with complex builds, custom module definitions, or monorepos, configure FOSSA's analysis using a .fossa.yml file in your project root. See the configuration reference for details.

Performance and accuracy

CI/CD scanning consistently outperforms automated builds for large or complex projects:

FOSSA processes provided builds at higher priority and skips resource-intensive build steps
Analysis operates inside your existing environment, eliminating false positives from test dependencies, build configuration differences, and non-deterministic build behavior
Explicit module definitions let you exclude irrelevant targets (docs, test modules) from the report

Limitations

Private dependencies: dependencies behind a firewall or requiring authentication still need to be accessible from your FOSSA instance for license and vulnerability analysis

Troubleshooting

Upload fails on an unpublished branch

FOSSA uses VCS revision detection to associate the upload with a branch. If the revision hasn't been pushed to your Git host yet, FOSSA can't find it.

Run fossa analyze on a published branch, or pass the revision explicitly:

Shell

fossa analyze --revision <commit-hash>

`git` not available in the CI environment

Without git, the CLI can't infer the project name or revision.

Pass them explicitly:

Shell

fossa analyze --project my-project --revision 1.0.0

Analysis succeeds but results look wrong

The CI environment may include test or dev dependencies that aren't in your production build.

Ensure the environment is clean and mirrors your production build configuration before running fossa analyze. Ideally, run it immediately after your production build step.

On-premises: analysis fails to connect

The CLI may be pointing at the wrong server or using the wrong API key.

Check that server and apiKey in your .fossa.yml point at your local FOSSA instance. Verify the configuration works locally before debugging CI.

What's next

Issue Scanners: Configure which categories of issues (licensing, security, quality) are detected and how they gate your builds.
Pull Request Checks: Set up status checks to block merges when fossa test detects unresolved issues.
Automatic Updates: Configure how FOSSA re-analyzes your project when new code is pushed or on a schedule.