CI/CD Scanning
Overview
The preferred way to integrate code with FOSSA when you have an existing build environment is called "CI/CD scanning".
In this model, FOSSA will not run analysis of your code from within the service. Instead, you will provide a pre-configured build environment and run a plugin built by FOSSA to analyze and upload dependency data from your build tasks.
By using this approach, you can take advantage of your CI / dev environments for dramatically faster, more accurate and reliable dependency reports, regardless of how large and complicated your build is.
Pros
- Dramatically increased performance and reliability
- Zero false positives: guranteed to match your exact build behavior and configuration
- Dead-simple integration model for complex builds (uses existing config)
- Publish and view reports without granting any code access to FOSSA
Cons
- Builds no longer run within FOSSA, meaning you may no longer trigger analysis from within the UI
- Requires a plugin to publish results from an external, successfully-running build environment (i.e. a CI or developer machine)
Quickstart
Setup
- install fossa cli
curl https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash
- initialize repo
fossa init
CICD tooling
- build your project
- run
FOSSA_API_KEY=<key> fossa analyze
* Triggers an analysis of your project's dependencies on Fossa's servers. It's important to run before starting tests so that analysis can be executed while tests are run - execute tests
- check license issues with
fossa test
* Blocks the build until the analysis has completed. Should there be any issues, the build will fail.
Migrating from Repository Scanning to CI/CD Scanning
Integration with
fossa-cli
If you've uploaded your build initially through
fossa-cli
, then you are already using CI/CD Scanning! You can skip this section.
CI/CD Scanning can enabled on any project that you've improved from a code host. To start, import or pick a project that you'd like to integrate and follow the steps below:
1. Turn on CI/CD Scanning
Navigate into Project > Settings > Builds & Languages and click "Enable Provided Builds".

Then, click on "Save" to submit.
Once finished, FOSSA will no longer automatically run builds and scans on your code, but instead wait for data to be provided by your build.

2. Installing the fossa
Build Plugin
fossa
Build PluginThe FOSSA build plugin (fossa
) is a lightweight CLI
tool that interrogates an existing build environment for third-party code and uploads them to FOSSA for deeper analysis. It runs on all major platforms including Linux (Unix), OSX (Darwin) and Windows.
Run the following command from within your terminal or CI machine to get the latest version:
curl https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash
Then check your installation:
fossa --help
3. Configuring your Repository
Follow the configuration guide on the GitHub to get started with configuring your repository.
Once done, simply running fossa
should succeed and generate a report link!
⣾ Uploading build results (2/2)...
============================================================
View FOSSA Report:
http://app.fossa.io/projects/{LINK_TO_REPORT}
============================================================
Troubleshooting:
- If your
cli.fetcher
configuration specifies a value that isn'tcustom
, then FOSSA will rely on your VCS for revision information. That means, reports can only be published for revisions that are accessible to the FOSSA service node. If you runfossa
on an unpublished branch / revision, the dependency analysis will succeed but upload will fail. - If you are running within a
git
repo,fossa
will infer the project name, version and ID fromgit
. If this is unavailable, you must pass the--locator
flag with the revision ID (i.e.git+github.com/org/repo$revision_hash
). - If you are using a custom or on-prem installation of FOSSA, make sure your
cli.api_key
andcli.server
are configured to point at your local FOSSA server.
Documentation for the full .fossa.yml
config is coming soon.
4. Integrating into CI and Build Machines
To update a project using CI/CD Scanning, you must invoke fossa
continuously as new revisions are published through a CI or Build Machine. The typical fully-integrated workflow looks something like this:
- Revision is published to Git host
- CI runs to clone / update Git repo
- Build scripts run and succeeds at generating a production artifact
fossa
runs and analyzes artifact/build environment AFTER build successfossa
uploads build results to be analyzed and scanned- CI runs tests and other plugins (i.e.
license-cli
), one of which checks for scan status from FOSSA and fail a build if issues are found
Currently you must manually add a step to your build to invoke fossa
. Later on, tool-specific wrappers will be available for fossa
to provide a better experience for select common integrations (i.e. Jenkins, Bitbucket, Gitlab).
Contact us if your workflow diverges from this dramatically.
Considerations:
- To ensure accuracy, make sure your machine is running a clean environment with the same configuration as your final production build. Otherwise, you may include test and development dependencies in the report.
fossa
requires a build to have succeeded before it is invoked. Ideally, you provide the build command andfossa
runs after it finishes. If you wantfossa
to run a default build command for you, you can specify the--install
flag.- If
git
is unavailable, you can configure the revision to publish to by specifying its ID via the--locator
flag. - If uploads are failing, confirm that your configuration and API key runs locally. If on-prem, make sure the server and key are both pointed at the right FOSSA server.
- For security reasons, it is reccomended to pass
FOSSA_API_KEY
as an environment variable rather than embedding it into the.fossa.yml
file.
Performance & Accuracy
Most users will notice a significant increase in performance and reliability after integrating CI/CD Scanning, enabling a smoother experience when running within the development and triage workflow. This is for a few reasons:
- CI/CD Scanning still requires some processing from FOSSA, but often much less work. As a result, CI/CD Scanning is given higher priority and skip built-in limitations / resource safeguards within FOSSA's build service.
- CI builds are often fast and highly optimized; developers and services set up caches and configuration to improve build timing that CI/CD Scanning can leverage
- When running CI/CD Scanning, FOSSA will never download or scan any of your code, skipping massive amounts of work when processing large codebases
In addition, users will experience much higher accuracy within reports and issue scans. When using CI/CD Scanning, FOSSA's analysis operates within your existing build to get a perfect replica of your build configuration and behavior.
This permanently resolves a variety of false positives from the following sources that affect build behavior:
- Unused test and development dependencies
- Dependencies mediated by build logic, constaint solvers and configuration
- Build "magic" or non-deterministic build system implementations
- Environmental factors (network conditions, caches, time of day, or even changes in transitive dependencies between builds)
- Variable build tasks that can generate different targets/artifacts
On top of this, explicit module definitions allow you to skip irrelevant modules that aren't built and bundled (i.e. documentation or test modules). Integrating CI/CD Scanningcan often reduce false positives by over 90%.
Limitations with CI/CD Scanning
CI/CD Scanning is a model that makes minor trade offs for major improvements in speed, accuracy and portability:
- Private dependencies (authenticated or behind a firewall) will still require access from your FOSSA instance
- License and code scanners will still be run on all 3rd party dependencies, but will not be run on any 1st-party code (as they are not shipped with the cli).
Updated about 1 month ago