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 and quality 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.

Release Notes

Compatibility

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:

Sonatype CLI Setup Action

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
`iq-cli-version`	Either this or `iq-cli-download-url` is required.	Sonatype CLI version to be used. It could be `latest` or a full version (e.g. `2.1.0`).
`iq-cli-download-url`	Either this or `iq-cli-version` is required.	URL from where the Sonatype CLI JAR file will be downloaded. The URL must meet the following requirements: Must use HTTPS protocol for security Must end with the filename format: `nexus-iq-cli-{version}.jar` The `{version}` must follow this pattern: `major.minor.patch-build` (e.g., `2.7.0-01`) Example: https://download.sonatype.com/clm/scanner/nexus-iq-cli-2.7.0-01.jar Note For security, the action validates the downloaded file using checksums. Only unmodified official releases of the CLI will work.
`iq-cli-download-auth`	Optional	Credentials for accessing `iq-cli-download-url`. Format: `username:password`. If provided the value will be used for basic authentication.

Parameter

Required/Optional

Description

iq-cli-version

Either this or iq-cli-download-url is required.

Sonatype CLI version to be used. It could be latest or a full version (e.g. 2.1.0).

iq-cli-download-url

Either this or iq-cli-version is required.

URL from where the Sonatype CLI JAR file will be downloaded.

The URL must meet the following requirements:

Must use HTTPS protocol for security
Must end with the filename format: nexus-iq-cli-{version}.jar
The {version} must follow this pattern: major.minor.patch-build (e.g., 2.7.0-01)

Example:

https://download.sonatype.com/clm/scanner/nexus-iq-cli-2.7.0-01.jar

Note

For security, the action validates the downloaded file using checksums. Only unmodified official releases of the CLI will work.

iq-cli-download-auth

Optional

Credentials for accessing iq-cli-download-url. Format: username:password.

If provided the value will be used for basic authentication.

Sonatype CLI Run Action

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
`iq-server-url`	Required	Lifecycle (IQ Server) URL.
`username`	Required	The username to authenticate with Lifecycle (IQ Server).
`password`	Required	The password to authenticate with Lifecycle (IQ Server).
`application-id`	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.
`organization-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.
`scan-targets`	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.
`stage`	Optional	Specify the development lifecycle stage for the analysis. Defaults to the `build` stage.
`result-file`	Optional	If set, the analysis output (in JSON format) will be uploaded as a run artifact with the specified name.
`module-exclude`	Optional	Specify module files to ignore via Apache Ant-styled patterns .
`fail-on-policy-warnings`	Optional	Causes a failure of the evaluation if any warnings are encountered. Default: `false`.
`ignore-system-errors`	Optional	Ignore system errors (e.g. IO, Network, server, etc.) to avoid unintentional build failures. Default: `false`
`ignore-scanning-errors`	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: `false`.
`debug`	Optional	Enables debug logging for troubleshooting. Use with caution as this log may expose sensitive information. Default: `false`.
`keep-scan-file`	Optional	Retains and uploads the scan file as an action artifact. Default: `false`.
`proxy`	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.
`proxy-user`	Optional	Specify proxy credentials in the following format: `username:password`.
`include-sha-256`	Optional	If set, SHA256 checksums are included in the scan file. Default: `false`.
`exclude-maven-dependency-management`	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: `false`.
`sarif-file`	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.
`enable-reachability`	Optional	Since version 1.4.0, you can perform Reachability Analysis in Java or JVM language binaries to determine the method signatures that trigger a security vulnerability. Default: `false`.
`reachability-namespaces`	Optional	Since version 1.4.0, you can limit the Reachability Analysis to a specific namespace for faster, more precise results. Multiple namespaces can be delimited by space. Default: `empty`.
`enable-callflow`	Optional	Deprecated in version 1.4.0. Use `enable-reachability` instead.
`callflow-namespaces`	Optional	Deprecated in version 1.4.0. Use `reachability-namespaces` instead.

Output - Sonatype CLI Run Action

Parameter	Description
`scan-id`	Scan id result of the run operation. It can be used to access the Lifecycle report of related artifacts.
`report-url`	Link to navigate directly to the analysis report in Lifecycle (IQ Server).
`sarif-file`	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
`iq-server-url`	Required	Lifecycle (IQ Server) URL.
`username`	Required	The username to authenticate with Lifecycle (IQ Server).
`password`	Required	The password to authenticate with Lifecycle (IQ Server).
`application-id`	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.
`organization-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.
`scan-targets`	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.
`stage`	Optional	Specify the development lifecycle stage for the analysis. Defaults to the `build` stage.
`result-file`	Optional	If set, the analysis output (in JSON format) will be uploaded as a run artifact with the specified name.
`module-exclude`	Optional	Specify module files to ignore via Apache Ant-styled patterns .
`fail-on-policy-warnings`	Optional	Causes a failure of the evaluation if any warnings are encountered. Default: `false`.
`ignore-system-errors`	Optional	Ignore system errors (e.g. IO, Network, server, etc.) to avoid unintentional build failures. Default: `false`
`ignore-scanning-errors`	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: `false`.
`debug`	Optional	Enables debug logging for troubleshooting. Use with caution as this log may expose sensitive information. Default: `false`.
`keep-scan-file`	Optional	Retains and uploads the scan file as an action artifact. Default: `false`.
`proxy`	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.
`proxy-user`	Optional	Specify proxy credentials in the following format: `username:password`.
`include-sha-256`	Optional	If set, SHA256 checksums are included in the scan file. Default: `false`.
`exclude-maven-dependency-management`	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: `false`.
`sarif_file`	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.
`upload-sarif-file`	Optional	Enable this parameter to generate or use the generated `sarif-file` to update the "Code scanning" section under the GitHub repository's Security tab. Default: `false`. If `sarif-file` is not defined, the generated file will be named `result.sarif` by default, and it will be uploaded as an action artifact. GitHub Advanced Security is available for GitHub Enterprise and public repositories.
`enable-reachability`	Optional	Since version 1.4.0, you can perform a Reachability Analysis in Java or JVM language binaries to determine the method signatures that trigger a security vulnerability. Default: `false`.
`reachability-namespaces`	Optional	Since version 1.4.0, you can limit the Reachability Analysis to a specific namespace for faster, more precise results. Multiple namespaces can be delimited by space. Default: `empty`.
`reachability-entrypoint-strategy`	Optional	Specify the entrypoint strategy used for Java reachability analysis.
`enable-reachability-js`	Optional	Enable Reachability Analysis for JavaScript projects. Default: `false`.
`reachability-js-sources`	Optional	Specify JavaScript source patterns used for Reachability Analysis. This parameter is required when JavaScript reachability is enabled. Patterns should include application source files only and must not include test files or `node_modules`. Multiple patterns can be delimited by space. Default: `empty`.
`reachability-js-excludes`	Optional	Specify JavaScript exclude patterns for Reachability Analysis, such as tests or other non-relevant files. Multiple patterns can be delimited by space. Default: `empty`.
`reachability-node-path`	Optional	Specify the path to the Node.js executable used for JavaScript reachability analysis.
`reachability-js-project-root`	Optional	Specify the JavaScript project root directory where the main `package.json` file resides.
`ignore-reachability-errors`	Optional	Ignore Reachability Analysis errors when reachability analysis fails to run. Default: `false`.
`skip-java-setup`	Optional	Skip the automatic Java setup step. Use this when Java is already available in the runner environment or when you need to provide Java through your own approved mechanism. Default: `false`.
`enable-callflow`	Optional	Deprecated in version 1.4.0. Use `enable-reachability` instead.
`callflow-namespaces`	Optional	Deprecated in version 1.4.0. Use `reachability-namespaces` instead.

Output - Sonatype Evaluate Action

Parameter	Description
`scan-id`	Scan id result of the run operation. It can be used to access the Lifecycle report of related artifacts.
`report-url`	Link to navigate directly to the analysis report in Lifecycle (IQ Server).
`sarif-file`	Name of the generated SARIF file containing all found vulnerabilities, if configured.

GitHub Advanced Security

Integrations_-_GitHub_Actions_-_Lifecycle_vulnerabilities_displayed_as_GitHub_code_scanning_alerts_in_the_GitHub_Security_tab.png

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:
      contents: read          # Required by the checkout action
      security-events: write  # Required to upload SARIF results
      actions: read           # Required for workflow run info lookup

    steps:
    # some steps are omitted...
    # Check out your code
    - name: Checkout
      id: checkout
      uses: actions/checkout@v7

    # 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

Details view for an individual Lifecycle vulnerability alert in GitHub Advanced Security:

Fetch SBOM Action

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
`iq-server-url`	Required	Lifecycle (IQ Server) URL.
`username`	Required	The username to authenticate with Lifecycle (IQ Server).
`password`	Required	The password to authenticate with Lifecycle (IQ Server).
`application-id`	Required	Lifecycle (IQ Server) application ID.
`scan-id`	Required	The scan ID to fetch the report.
`sbom-standard`	Required	The SBOM standard: `spdx` or `cyclonedx`.
`sbom-format`	Optional	The output file format: `json` or `xml`. Default: `json`.
`sbom-version`	Optional	The version of the SBOM standard. Available CycloneDX versions: `1.2`, `1.3`, `1.4`, `1.5`, `1.6`, `1.7`. Default version for CycloneDX is `1.7`. Available SPDX versions: `2.2`, `2.3`
`artifact-name`	Optional	The name of the artifact to be uploaded. Default: `sbom-document`.
`push-dependency-graph`	Optional	If set, the dependency information from the fetched SBOM will be available in GitHub Insights Dependency Graph. Default: `false`.
`token`	Optional	GitHub Personal Access Token (PAT). Defaults to the PAT provided by the actions runner.

GitHub Enterprise Server

If you're using GitHub Enterprise Server (GHES) and encounter a warning message such as Fail to upload artifact from Github Enterprise server, it's because GHES doesn't currently support @actions/upload-artifact@v4.

To resolve this, add the following step to your workflow to use @actions/upload-artifact@v3 instead:

- name: Upload Result File as an artifact
 if: ${{ !cancelled() && steps.run-iq-cli.outputs.result-file-path }}
 uses: actions/upload-artifact@v3
 env:
 NODE_TLS_REJECT_UNAUTHORIZED: 0
 with:
 name: result-file
 path: ${{ steps.run-iq-cli.outputs.result-file-path }}

Possible outputs for run-iq-cli that can be used with this artifact upload step:

result-file-path
sarif-file-path
scan-file-path

Possible outputs for fetch-sbom :

sbom-file-path

Usage Example - GitHub Enterprise Server

name: Sonatype Workflow
on: workflow_dispatch
jobs:
 sonatype-cli:
 runs-on: self-hosted
 steps: 
 - name: Evaluate Sonatype
 id: evaluate
 uses: sonatype/actions/evaluate@v1
 with:
 username: ${{ secrets.LIFECYCLE_USERNAME }}
 password: ${{ secrets.LIFECYCLE_PASSWORD }}
 iq-server-url: https://int-test.sonatype.app/platform
 application-id: github-actions
 result-file: result-file
 keep-scan-file: true
 debug: false
 scan-targets: '**'
 sarif-file: sarif-file.sarif
 
 #Step the user needs to add to upload the artifact 
 - name: Upload Result File as an artifact
 if: ${{ !cancelled() && steps.evaluate.outputs.result-file-path }}
 uses: actions/upload-artifact@v3
 env:
 NODE_TLS_REJECT_UNAUTHORIZED: 0
 with:
 name: resul-file
 path: ${{ steps.evaluate.outputs.result-file-path }}
 
 #Step the user needs to add to upload the artifact 
 - name: Upload Scan File as an artifact
 if: ${{ !cancelled() && steps.evaluate.outputs.scan-file-path }}
 uses: actions/upload-artifact@v3
 env:
 NODE_TLS_REJECT_UNAUTHORIZED: 0
 with:
 name: scan-file
 path: ${{ steps.evaluate.outputs.scan-file-path }}

 #Step the user needs to add to upload the artifact 
 - name: Upload Sarif File as an artifact
 if: ${{ !cancelled() && steps.evaluate.outputs.sarif-file-path }}
 uses: actions/upload-artifact@v3
 env:
 NODE_TLS_REJECT_UNAUTHORIZED: 0
 with:
 name: sarif-file
 path: ${{ steps.evaluate.outputs.sarif-file-path }}

 # Fetch the SBOM file associated with the previous Sonatype CLI run
 - name: Fetch SBOM
 id: fetch-sbom
 uses: sonatype/actions/fetch-sbom@v1
 if: ( success() || failure() ) && steps.evaluate.outputs.scan-id
 with:
 iq-server-url: https://int-test.sonatype.app/platform
 username: ${{ secrets.LIFECYCLE_USERNAME }}
 password: ${{ secrets.LIFECYCLE_PASSWORD }}
 application-id: github-actions
 scan-id: ${{ steps.evaluate.outputs.scan-id }}
 sbom-standard: cyclonedx
 sbom-version: 1.5
 artifact-name: my-sbom
 
 #Step the user needs to add to upload the artifact 
 - name: Upload SBOM file as artifact
 if: ${{ !cancelled() && steps.fetch-sbom.outputs.sbom-file-path }}
 uses: actions/upload-artifact@v3
 env:
 NODE_TLS_REJECT_UNAUTHORIZED: 0
 with:
 name: sbom
 path: ${{ steps.fetch-sbom.outputs.sbom-file-path }}

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

Reachability Analysis

See Reachability Analysis with Sonatype for GitHub Actions for how to enable Reachability in Java/JVM and JavaScript builds covering the required permissions, usage examples, and configuration options including entry point strategies and tips on narrowing scope via namespaces.

Exit Codes

The pipelines emit the following exit codes:

Exit Code	Description
0	Success
1	Policy violation
2	Scanning error
3	Reachability error
4	Configuration error
5	Connectivity error
6	Local I/O error
7	Authentication error

The pipelines now emit the following output variables:

Output Variable	Description	Values
`cli-exit-code`	Exit code returned by the IQ CLI.	0=SUCCESS, 1=POLICY_VIOLATION, 2=SCANNING_ERROR, 3=REACHABILITY_ERROR, 4=CONFIGURATION_ERROR, 5=CONNECTIVITY_ERROR, 6=LOCAL_IO_ERROR, 7=AUTH_ERROR, 99=INTERNAL_ERROR.
`cli-exit-category`	Category name for the exit code.	Examples: SUCCESS, POLICY_VIOLATION, CONNECTIVITY_ERROR.
`cli-exit-message`	Message associated with the exit code from the IQ CLI.

Usage example:

- name: Check result
 if: always()
 run: |
 echo "Exit code: ${{ steps.iq-scan.outputs.cli-exit-code }}"
 echo "Category: ${{ steps.iq-scan.outputs.cli-exit-category }}"

Centralized CI configuration

To centrally manage supported CI evaluation settings for GitHub Actions workflows through the Lifecycle organization and application hierarchy, see the CI Configuration REST API.