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

1. Dramatically increased performance and reliability
2. Zero false positives: guranteed to match your exact build behavior and configuration
3. Dead-simple integration model for complex builds (uses existing config)
4. Publish and view reports without granting any code access to FOSSA

Cons

1. Builds no longer run within FOSSA, meaning you may no longer trigger analysis from within the UI
2. Requires a plugin to publish results from an external, successfully-running build environment (i.e. a CI or developer machine)

Quickstart

Setup

1. install fossa cli curl https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash
2. initialize repo fossa init

CICD tooling

3. build your project
4. 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
5. execute tests
6. 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

The 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't custom, 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 run fossa 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 from git. 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 and cli.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:

1. Revision is published to Git host
2. CI runs to clone / update Git repo
3. Build scripts run and succeeds at generating a production artifact
4. fossa runs and analyzes artifact/build environment AFTER build success
5. fossa uploads build results to be analyzed and scanned
6. 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 and fossa runs after it finishes. If you want fossa 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:

1. 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.
2. 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
3. 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:

1. Unused test and development dependencies
2. Dependencies mediated by build logic, constaint solvers and configuration
3. Build "magic" or non-deterministic build system implementations
4. Environmental factors (network conditions, caches, time of day, or even changes in transitive dependencies between builds)
5. 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:

1. Private dependencies (authenticated or behind a firewall) will still require access from your FOSSA instance
2. 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).