CircleCI

This guide is for you to set up a FOSSA project with a CircleCI workflow.

Getting Started

The CircleCI integration requires fossa-cli our open source dependency analysis client, to be installed on your CI machine. The client supports all 3 major operating systems (Unix, Darwin/OSX and Windows).

To test the CLI, you can install it in your local environment using the command below or download it directly from our Github Releases page.

curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash

# view `fossa` help text
fossa --help

Setup your CircleCI Environment

First, grab a FOSSA API Key from your FOSSA account under your Integration Settings.

NOTE: If you are the maintainer of a public repository you should consider making your API key a Push Only Token.

Then, add it to your CircleCI environment variables as FOSSA_API_KEY:

Add FOSSA steps to config.yml

Once the environment variable is ready, it's time to edit your .circleci/config.yml file.

First, add a step to install fossa-cli when your build starts. Usually the best place to include this is right before the checkout step of your build job when you're still installing the environment pre-reqs:

...
jobs:
  build:
    ...
    steps: 
      - run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
      - checkout
...

Next, add a step to run the fossa analyze command you just installed in order to upload dependency data from your CircleCI build:

- run:
	command: fossa analyze
	working_directory: $YOUR_CODE_DIRECTORY

We recommend inserting this in your .circleci/config.yml file RIGHT AFTER your build/install steps (usually the end of your build section) but BEFORE any tests run.

Full Example:

version: 2
jobs:
  build:
    docker:
      - image: circleci/<language>:<version TAG>
    steps:
      - run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
      - checkout
      - run: <build command>
      - run:
        command: fossa analyze
        working_directory: <repo_dir>
workflows:
  version: 2
  build:
    jobs:
      - build

Now with every CI build, you will be uploading dependency data for analysis back to FOSSA.

📘

Customizing with .fossa.yml

To customize your fossa task behavior, add a .fossa.yml file to the root of your VCS.

View the .fossa.yml reference on GitHub.

Blocking CI Builds w/ FOSSA Issue Status

You an also create a step in CircleCI that will allow you to pass/fail a build based off your scan status in FOSSA.

To accomplish this, simply add a call to fossa test into your test section.

- run:
	command: fossa test
	working_directory: <repo_dir>

The fossa test command will poll app.fossa.io or your local FOSSA appliance for updates on your scan status until it gets a response. Then, it will report a relevant exit status to the CI step (to block a failing build) and render rich details about issues directly inline your CircleCI test results.

You can customize a timeout on this step using the fossa test --timeout {seconds} flag documented here. The default timeout is set to 600 seconds (10 minutes), but will only be hit in exceptional cases -- most scans should return well under the timeout window.

Full Example:

version: 2
jobs:
  build:
    docker:
      - image: circleci/<language>:<version TAG>
    steps:
      - run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
      - checkout
      - run: <build command>
      - run:
        command: fossa analyze
        working_directory: <repo_dir>
  test:
    docker:
      - image: circleci/<language>:<version TAG>
    steps:
      - checkout
      - run: <test command>
      - run:
        command: fossa test
        working_directory: <repo_dir>
workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test

Triggering Updates with Webhooks

In exceptional cases, you may require your CI to tell FOSSA to pull an update for your code. This is not necessary for most users, but can be accomplished if you are using Automated Builds and have no other possible update strategy.

To do this, add the following to your circle.yml file:

notify:
  webhooks:
    - url: http://app.fossa.io/hooks/circleci

You will also have to update your project settings in FOSSA by navigating to Project > Settings > Update Hooks, and selecting CircleCI in the dropdown.