Sonatype GitHub Actions
This integration provides a set of GitHub Actions for interacting with different Sonatype products directly within your GitHub workflows.
Sonatype GitHub Actions also support integration with GitHub Code Scanning, part of the GitHub Advanced Security feature, which displays detected vulnerabilities on the GitHub Security tab. As you'll find in the documentation below, you can use the evaluate
or run-iq-cli
actions in combination with the upload-sarif-file
parameter to take advantage of this functionality. GitHub Advanced Security is available for GitHub Enterprise customers and public repositories.
The Sonatype GitHub Actions integration is available on the GitHub Marketplace.
Sonatype Evaluate Action
An action for evaluations against a Sonatype Lifecycle instance in GitHub workflows. It sets up Sonatype CLI and runs it to execute the evaluation. This convenient composite action enables developers to start running Lifecycle evaluations quickly.
Internally, it uses 3 actions with some predefined parameters: Setup Java (which makes Java available for GitHub runners by selecting an appropriate version for the Sonatype CLI) and the following 2 actions which you can configure for more fine-grained control:
An action for setting up Sonatype CLI as a tool that is available for GitHub runners and subsequent actions. The action downloads and configures the requested version of the Sonatype CLI. Note that this is a prerequisite for the Run Sonatype CLI action provided in this action set.
Usage Example - Sonatype CLI Setup Action
name: Sonatype Workflow on: push jobs: sonatype-cli: runs-on: ubuntu-latest steps: - name: Setup Sonatype CLI uses: sonatype/actions/setup-iq-cli@v1 with: iq-cli-version: 1.179.0-01
Parameters - Sonatype CLI Setup Action
Parameter | Required/Optional | Description |
---|---|---|
| Either this or | Sonatype CLI version to be used. It could be a full version (e.g. 1.179.0-01), a short version (e.g. 179) or latest. |
| Either this or | URL from where the Sonatype CLI JAR file will be downloaded. |
An action for running Sonatype CLI in GitHub workflows.
This action (i.e.
sonatype/actions/run-iq-cli
) needs to have Sonatype CLI and a JDK properly configured to be able to work.Setup Sonatype CLI action is provided in this action set.
Sonatype CLI versions 174 and older require Java 8 or 11 to run. For Sonatype CLI release 175 and above, we recommend using Java 17, which will be the minimum supported Java version for releases 180+.
Usage Example - Sonatype CLI Run Action
name: Sonatype Workflow on: push jobs: sonatype-cli: runs-on: ubuntu-latest steps: # Some steps are omitted... # Make Sonatype CLI available to GitHub runners - name: Setup Sonatype CLI uses: sonatype/actions/setup-iq-cli@v1 with: iq-cli-version: 1.179.0-01 # Sonatype CLI requires Java to run - name: Set up JDK 17 uses: actions/setup-java@v3 with: distribution: 'temurin' java-version: '17' # Run Sonatype CLI - name: Run Sonatype CLI uses: sonatype/actions/run-iq-cli@v1 with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-targets: target/*.jar
Parameters - Sonatype CLI Run Action
Parameter | Required/Optional | Description |
---|---|---|
| Required | Lifecycle (IQ Server) URL. |
| Required | The username to authenticate with Lifecycle (IQ Server). |
| Required | The password to authenticate with Lifecycle (IQ Server). |
| Required | Lifecycle (IQ Server) application ID. When Automatic Applications is enabled and the application ID has not yet been used, a new application will be created with the given ID. |
| Optional | The ID for the Lifecycle organization to which the application belongs. When automatic application creation is enabled and the application does not exist, it will be created under the organization having the provided organization ID. See Automatic application creation with the CLI for more details. |
| Required | Space-separated list of paths to specific files, directories, or docker images. Apache Ant-styled patterns are allowed. See supported file formats in Analysis. |
| Optional | Specify the development lifecycle stage for the analysis. Defaults to the |
| Optional | If set, the analysis output (in JSON format) will be uploaded as a run artifact with the specified name. |
| Optional | Specify module files to ignore via Apache Ant-styled patterns . |
| Optional | Causes a failure of the evaluation if any warnings are encountered. Default: |
| Optional | Ignore system errors (e.g. IO, Network, server, etc.) to avoid unintentional build failures. Default: |
| Optional | Ignore scanning errors (e.g. invalid files, inaccessible files, etc). It is useful when the code base contains invalid files for testing purposes. Scanning these files may cause unintentional build failures. Default: |
| Optional | Enables debug logging for troubleshooting. Use with caution as this log may expose sensitive information. Default: |
| Optional | Retains and uploads the scan file as an action artifact. Default: |
| Optional | Specify a proxy to use when connecting to Lifecycle (IQ Server). This property is set using the format host[:port], otherwise, the CLI uses the default HTTP proxy set with the JVM. |
| Optional | Specify proxy credentials in the following format: |
| Optional | If set, SHA256 checksums are included in the scan file. Default: |
| Optional | Enable this parameter to limit analysis to the projects dependencies section of a pom file while excluding the components under the dependencyManagement section. Default: |
| Optional | Generates a SARIF file with a specified name containing all identified vulnerabilities. The SARIF file extension must be .sarif or .json. The generated file will be uploaded as an action artifact. |
Output - Sonatype CLI Run Action
Parameter | Description |
---|---|
| Scan id result of the run operation. It can be used to access the Lifecycle report of related artifacts. |
| Link to navigate directly to the analysis report in Lifecycle (IQ Server). |
| Name of the generated SARIF file containing all found vulnerabilities, if configured. |
Usage Example - Sonatype Evaluate Action
name: Sonatype Workflow on: push jobs: sonatype-cli: runs-on: ubuntu-latest steps: # some steps are omitted... # Check out your code - name: Checkout id: checkout uses: actions/checkout@v4 # Perform an evaluation - name: Run evaluate action id: evaluate uses: sonatype/actions/evaluate@v1 with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-targets: package.json # Print out the results - name: Log evaluate action output run: echo "${{ steps.evaluate.outputs.scan-id }} ${{ steps.evaluate.outputs.report-url }}"
Parameters - Sonatype Evaluate Action
Parameter | Required/Optional | Description |
---|---|---|
| Required | Lifecycle (IQ Server) URL. |
| Required | The username to authenticate with Lifecycle (IQ Server). |
| Required | The password to authenticate with Lifecycle (IQ Server). |
| Required | Lifecycle (IQ Server) application ID. When Automatic Applications is enabled and the application ID has not yet been used, a new application will be created with the given ID. |
| Optional | The ID for the Lifecycle organization to which the application belongs. When automatic application creation is enabled and the application does not exist, it will be created under the organization having the provided organization ID. See Automatic application creation with the CLI for more details. |
| Required | Space-separated list of paths to specific files, directories, or docker images. Apache Ant-styled patterns are allowed. See supported file formats in Analysis. |
| Optional | Specify the development lifecycle stage for the analysis. Defaults to the |
| Optional | If set, the analysis output (in JSON format) will be uploaded as a run artifact with the specified name. |
| Optional | Specify module files to ignore via Apache Ant-styled patterns . |
| Optional | Causes a failure of the evaluation if any warnings are encountered. Default: |
| Optional | Ignore system errors (e.g. IO, Network, server, etc.) to avoid unintentional build failures. Default: |
| Optional | Ignore scanning errors (e.g. invalid files, inaccessible files, etc). It is useful when the code base contains invalid files for testing purposes. Scanning these files may cause unintentional build failures. Default: |
| Optional | Enables debug logging for troubleshooting. Use with caution as this log may expose sensitive information. Default: |
| Optional | Retains and uploads the scan file as an action artifact. Default: |
| Optional | Specify a proxy to use when connecting to Lifecycle (IQ Server). This property is set using the format host[:port], otherwise, the CLI uses the default HTTP proxy set with the JVM. |
| Optional | Specify proxy credentials in the following format: |
| Optional | If set, SHA256 checksums are included in the scan file. Default: |
| Optional | Enable this parameter to limit analysis to the projects dependencies section of a pom file while excluding the components under the dependencyManagement section. Default: |
| Optional | Generates a SARIF file with a specified name containing all identified vulnerabilities. The SARIF file extension must be .sarif or .json. The generated file will be uploaded as an action artifact. |
| Optional | Enable this parameter to generate or use the generated If GitHub Advanced Security is available for GitHub Enterprise and public repositories. |
Output - Sonatype Evaluate Action
Parameter | Description |
---|---|
| Scan id result of the run operation. It can be used to access the Lifecycle report of related artifacts. |
| Link to navigate directly to the analysis report in Lifecycle (IQ Server). |
| Name of the generated SARIF file containing all found vulnerabilities, if configured. |
GitHub Advanced Security
Prerequisites
In order to use the GitHub Advanced Security feature, you must grant your workflow the security-events: write
permission.
Usage Example - Sonatype Evaluate Action with Results in GitHub Security Tab
name: Workflow for GitHub Advanced Security on: push jobs: sonatype-cli: runs-on: ubuntu-latest permissions: security-events: write steps: # some steps are omitted... # Check out your code - name: Checkout id: checkout uses: actions/checkout@v4 # Perform an evaluation - name: Run evaluate action id: evaluate uses: sonatype/actions/evaluate@v1 with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-targets: package.json upload-sarif-file: true
Fetch SBOM Action
Note
The Fetch SBOM Action is not currently supported in GitHub Enterprise Server environments.
An action for retrieving an SBOM (Software Bill of Materials) file associated with a previous Lifecycle evaluation. It supports both the CycloneDX and SPDX standards.
Usage Example - Fetch SBOM Action
name: Sonatype Workflow on: push jobs: sonatype-cli: runs-on: ubuntu-latest steps: # Some steps are omitted... # Evaluate Sonatype CLI - name: Evaluate Sonatype CLI id: evaluate uses: sonatype/actions/evaluate@v1 with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-targets: target/*.jar # Fetch the SBOM file associated with the previous Sonatype CLI run - name: Fetch SBOM uses: sonatype/actions/fetch-sbom@v1 if: ( success() || failure() ) && steps.evaluate.outputs.scan-id with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-id: ${{ steps.evaluate.outputs.scan-id }} sbom-standard: cyclonedx sbom-version: 1.5 artifact-name: my-sbom
Parameters - Fetch SBOM Action
Parameter | Required/Optional | Description |
---|---|---|
| Required | Lifecycle (IQ Server) URL. |
| Required | The username to authenticate with Lifecycle (IQ Server). |
| Required | The password to authenticate with Lifecycle (IQ Server). |
| Required | Lifecycle (IQ Server) application ID. |
| Required | The scan ID to fetch the report. |
| Required | The SBOM standard: |
| Optional | The output file format: |
| Optional | The version of the SBOM standard. Available CycloneDX versions: |
| Optional | The name of the artifact to be uploaded. Default: |
| Optional | If set, the dependency information from the fetched SBOM will be available in GitHub Insights Dependency Graph. Default: |
| Optional | GitHub Personal Access Token (PAT). Defaults to the PAT provided by the actions runner. |
Usage Example - Sonatype GitHub Actions
Here's a typical usage example that evaluates an npm project against a Sonatype Lifecycle instance and retrieves the associated SBOM (Software Bill of Materials) file:
name: Sonatype Workflow on: push jobs: sonatype-cli: runs-on: ubuntu-latest steps: # Check out your code - name: Checkout id: checkout uses: actions/checkout@v4 # Perform an evaluation - name: Run evaluate action id: evaluate uses: sonatype/actions/evaluate@v1 with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-targets: package.json package-lock.json # Fetch the SBOM file associated with the evaluation - name: Fetch SBOM uses: sonatype/actions/fetch-sbom@v1 if: ( success() || failure() ) && steps.evaluate.outputs.scan-id with: iq-server-url: https://your.lifecycle.server username: ${{ secrets.LIFECYCLE_USERNAME }} password: ${{ secrets.LIFECYCLE_PASSWORD }} application-id: lifecycle-app scan-id: ${{ steps.evaluate.outputs.scan-id }} sbom-standard: cyclonedx sbom-version: 1.5 sbom-format: json artifact-name: lifecycle-app-sbom.json