CircleCI
Integrating FOSSA with 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
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.
Updated about 1 year ago