In this article you will learn how to integrate with SOOS using our standard Python based CLI script.
Python 3.7 or higher - https://www.python.org/downloads/
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
- In the SOOS Integration Scrip modal window, click the Download button and get the latest release of the
- Create a new folder in your codebase or locally
- Place the
soos.pyfiles downloaded in step 1 in
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).
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
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.
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.
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.
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.