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

github-actions | Repository for the GitHub Actions Integration

github-actions

Changelog

Version 1.13.0 (July 08, 2026)

• Introduced granular exit codes
• Minor bug fixes

Version 1.12.0 (June 05, 2026)

• Added support for .NET reachability analysis
• Added support for reachability analysis evidence
• Added the skip-java-setup input parameter to the evaluate action, which bypasses Java setup when enabled

Version 1.11.1 (May 11, 2026)

• Maintenance release

Version 1.11.0 (May 08, 2026)

• Updated all GitHub Actions to use the Node.js 24 runtime, which is the default Node version on GitHub-hosted runners
• Added an extra layer of security by switching to immutable releases

Version 1.10.0 (April 10, 2026)

• Added support for API-based CI configuration
• Added support for Sonatype Container Scanner
• Added support for zstd-compressed Docker image layers
• Fixed an issue with memory handling during container scanning

Version 1.9.3 (March 09, 2026)

• Fixed an issue where the SARIF file was deleted too early, preventing successful upload

Version 1.9.2 (March 06, 2026)

• Temporary workspace files are now cleaned up earlier during the pipeline run

Version 1.9.1 (February 10, 2026)

• Added basic authentication support for the iq-cli-download-url parameter

Version 1.9.0 (December 23, 2025)

• Added support for JavaScript reachability analysis

Version 1.8.2 (December 05, 2025)

• Fixed an edge case where scans failed for npm projects

Version 1.8.1 (December 04, 2025)

• Maintenance release

Version 1.8.0 (November 25, 2025)

• Implemented security controls for the iq-cli-download-url parameter in the setup-iq-cli action

Version 1.7.0 (November 07, 2025)

• Added support for npm workspaces
• Improved scan performance for pnpm-lock.yaml files

Version 1.6.2 (October 09, 2025)

• Added Priorities Report URL to Build Summary
• Added support for Docker Client v28 in Docker Image Analysis
• Added support for scanning pnpm-lock.yaml v9 manifest files

Version 1.6.1 (September 12, 2025)

• Added support for analyzing Java 25 bytecode

Version 1.6.0 (August 18, 2025)

• Added support for analyzing Java 23 and Java 24 bytecode

Version 1.5.1 (July 11, 2025)

• Maintenance release

Version 1.5.0 (June 13, 2025)

• Added support for downloading SBOMs in SPDX v2.2
• Added support for semver versioning to the iq-cli-version property in setup-iq-cli action

Version 1.4.3 (May 09, 2025)

• Maintenance release

Version 1.4.2 (April 30, 2025)

• Fixed a Reachability Analysis compatibility issue with previous IQ Server versions

Version 1.4.0 (April 22, 2025)

• Added new reachability parameters (-ra and -rn) to replace the previous options (-c and -cn)
• Fixed links to CVE details in IQ Server under Advanced Security

Version 1.3.1 (April 03, 2025)

• Maintenance release

Version 1.3.0 (March 06, 2025)

• Added both Priorities and Report URLs to Scan Results Summaries
• Added support for Java reachability analysis

Version 1.2.0 (February 05, 2025)

• Added branch name collection when a scan runs in a Git repository context

Version 1.1.2 (January 10, 2025)

• Added support for GitHub Enterprise Server runners to use upload-artifact@v3
• Fixed spawn E2BIG error when scan targets resolved to a big list of files
• Implemented post-execution tasks to leave self-hosted runners in a clean state

Version 1.1.1 (December 11, 2024)

• Added support for container: style scan patterns
• Fixed issue where environment variables were not recognized by the evaluate and run-iq-cli actions

Version 1.1.0 (November 22, 2024)

• Added support to generate a SARIF file as an artifact with policy violations findings
• Added support to upload evaluation results to GitHub Advanced Security

Version 1.0.5 (November 08, 2024)

• Maintenance release

Version 1.0.4 (October 10, 2024)

• Added optional download-url parameter for setup-iq-cli action
• Added support for CycloneDX v1.6 to fetch-sbom action
• Added IQ report link to the summary screen
• Improved the overall error message for run-iq-cli action failures

Version 1.0.3 (September 05, 2024)

• Maintenance release

Version 1.0.2 (August 19, 2024)

• Maintenance release

Version 1.0.1 (August 13, 2024)

• Fixed issue where the sonatype-iq-cli.jar file was incorrectly identified as a component
• The moduleExclude parameter now correctly supports a list of space-separated module names

Version 1.0.0 (July 19, 2024)

• Initial release

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

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

Output - Sonatype CLI Run Action

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

Output - Sonatype Evaluate Action

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:
      contents: read          # Required by the checkout action
      security-events: write  # Required to upload SARIF results
      actions: read           # Required for workflow run info lookup
    steps:
      - name: Checkout
        id: checkout
        uses: actions/checkout@v7
      - 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

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:
      - 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
      - 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

Exit Codes

The pipelines emit the following exit codes:

The pipelines now emit the following output variables:

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.

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.