Overview

In this article you will learn how to integrate with SOOS using our standard Python based CLI script.

Requirements

Integration Steps

Open the SOOS App, browse to Integrate > CI/CD/Repo > Script

Note the API Key (SOOS_API_KEY), Client ID (SOOS_CLIENT_ID) and Script (Script Integration) values, you will need these to setup Environment Variables.

Technical details for the script can be found here: https://github.com/soos-io/soos-ci-analysis-python

Repo Setup

  1. In the SOOS Integration Scrip modal window, click the Download button and get the latest release of the soos.py and requirements.txt files
  2. Create a new folder in your codebase or locally <codebase_root>/soos/workspace/
  3. Place the requirements.txt and soos.py files downloaded in step 1 in  <codebase_root>/soos/ folder.

Configure Your Environment

Setup Environment Variables

Create the SOOS_API_KEY and SOOS_CLIENT_ID environment variables. Use the API Key and Client ID values you collected from the SOOS App. (Refer to Integrations Steps section above).

Build Config

Create a shell script to run the script. You can get more details here: https://github.com/soos-io/soos-ci-analysis-python#running-the-script   

Parameters

Our CLI is highly configurable as it is designed to run in a number of scenarios. The only required parameters though, are the API Key and Client ID (which typically are setup as environment variables as defined above), and the project name.

Project Name

The project name is really up to you, but typically aligns with a repository name, module name or project/solution. It should always point to the same codebase between scans, otherwise the difference in manifests/packages will become apparent in the application.

Mode

The integration allows you to select the mode of running the script. Currently the integration supports three modes:

  • run_and_wait: to run the analysis synchronously. The results of the analysis will be displayed in the report url that you can copy from the script’s logs. This is the default option
  • async_init: to start async scanning, add other tasks. The script’s log will display the report status url
  • async_result: to wait for the scan to complete. The script’s log will display the report url

Branch and Build Info

If you are running scans against different branches, it is important to include as much branch information as possible using the built in branch/build parameters. This will ensure that you can easily track and compare scans between different branches for the same project.

Support for Maintenance Mode

The Python script will respond to SOOS API maintenance in two ways depending on how you have the 'on failure' parameter set. 

  • If set to fail the build (-of="fail_the_build"), then the script will exit with a non-successful exit code and fail the build during maintenance mode.
  • Otherwise a warning will be displayed and the scan will be skipped and appear to be successful in your CI/CD system.

Run It

To run the SOOS CLI against your code, just run the shell script created above. The shell script will use the environment variables that you created for the API Key and Client ID.