# Sonatype GitHub Actions

This integration provides a set of [GitHub Actions](https://github.com/features/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](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security), 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](https://github.com/marketplace/actions/sonatype-github-actions).

## Release Notes

github-actions | Repository for the GitHub Actions Integration

# [github-actions](https://sonatype.github.io/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

| Actions Version | IQ Server Version | GitHub Version | Node.js Runtime |
| --- | --- | --- | --- |
| 1.11.0 and higher | 165 and higher | Enterprise Server 3.12 and higher <br>github.com (rolling release) | 24 and higher |
| 1.0.0 to 1.10.0 | 165 and higher | Enterprise Server 3.12 and higher <br>github.com (rolling release) | 20 and higher |

## Sonatype Evaluate Action

An action for evaluations against a Sonatype Lifecycle instance in GitHub workflows. It sets up [Sonatype CLI](https://help.sonatype.com/en/sonatype-iq-cli.html "Sonatype IQ 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](https://help.sonatype.com/en/sonatype-github-actions.html#sonatype-cli-setup-action_body)

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](https://help.sonatype.com/en/sonatype-github-actions.html#sonatype-cli-run-action "Sonatype CLI Run Action") provided in this action set.

#### Usage Example - Sonatype CLI Setup Action

```yaml
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.<br>The URL must meet the following requirements:<br>- Must use HTTPS protocol for security<br>  <br>- Must end with the filename format: `nexus-iq-cli-{version}.jar`<br>  <br>- The `{version}` must follow this pattern: `major.minor.patch-build` (e.g., `2.7.0-01`)<br>  <br>**Example:**<br>```<br>https://download.sonatype.com/clm/scanner/nexus-iq-cli-2.7.0-01.jar<br>```<br>**Note**<br>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`.<br>If provided the value will be used for basic authentication. |

### [Sonatype CLI Run Action](https://help.sonatype.com/en/sonatype-github-actions.html#sonatype-cli-run-action_body)

An action for running [Sonatype CLI](https://help.sonatype.com/en/sonatype-iq-cli.html "Sonatype IQ 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](https://help.sonatype.com/en/sonatype-github-actions.html#sonatype-cli-setup-action "Sonatype CLI Setup 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

```yaml
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](https://help.sonatype.com/en/automatic-application.html "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](https://help.sonatype.com/en/automatic-application-with-the-cli.html "Using 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](https://ant.apache.org/manual/dirtasks.html#patterns) are allowed. See supported file formats in [Analysis](https://help.sonatype.com/en/analysis.html "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](https://ant.apache.org/manual/dirtasks.html#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 project's 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.<br>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

```yaml
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

```yaml
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](https://cyclonedx.org/) and [SPDX](https://spdx.dev/) standards.

### Usage Example - Fetch SBOM Action

```yaml
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

| 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`. Default version for CycloneDX is `1.6`. 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. |

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

```yaml
- 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](https://help.sonatype.com/en/ci-configuration-rest-api.html "CI Configuration REST API").

## Reachability Analysis

See [Reachability Analysis with Sonatype for GitHub Actions](https://help.sonatype.com/en/reachability-analysis-with-sonatype-for-github-actions.html "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.