# Sonatype Platform Plugin for Jenkins - Lifecycle

Sonatype Platform Plugin for Jenkins (previously known as the Nexus Platform Plugin for Jenkins) integrates Jenkins with Lifecycle to perform SCA open-source evaluations during the application build and to push the CI analysis back to CSM pull request.

This integration also works with [Nexus Repository](https://help.sonatype.com/en/nexus-platform-plugin-for-jenkins.html "Sonatype Platform Plugin for Jenkins - Nexus Repository").

## Release Notes

### jenkins-plugin

# jenkins-plugin

## Changelog

### Version 3.34.2 (July 13, 2026)

- Improved container scan error reporting by preserving the underlying failure cause

### Version 3.34.1 (July 08, 2026)

- Fixed an issue where the “Test Connection” button in Nexus Repository settings failed with newer versions of Nexus Repository
- Fixed Maven upload failures from Jenkins agent workspaces when an HTTP proxy is configured

### Version 3.34.0 (June 04, 2026)

- Added support for .NET reachability analysis
- Added support for reachability analysis evidence

### Version 3.33.2 (May 27, 2026)

- Maintenance release

### Version 3.33.1 (May 14, 2026)

- Maintenance release

### Version 3.33.0 (May 08, 2026)

- Added support for .NET reachability analysis
- Fixed scanning-error handling so failBuildOnScanningErrors: false is honored, preventing unparseable files from incorrectly marking builds as unstable or failed

### Version 3.32.0 (April 09, 2026)

- Added support for API-based CI configuration
- Updated the default scanner mode to Sonatype Container Scanner
- Improved upload performance to NXRM from remote agents
- Fixed an issue where Reachability Analysis could hang on Jenkins Kubernetes pod agents

### Version 3.31.0 (March 06, 2026)

- Jenkins temporary workspace folder is now used correctly instead of the default Java temporary folder
- Builds no longer default to Unstable on reachability errors when Fail on Build is set to false
- Added support for proxy configurations without credentials
- Added a Project Directory input field in the JavaScript Reachability Configuration UI
- Fixed issue where pipelines were incorrectly marked as failed when reachability analysis did not run

### Version 3.30.2 (February 05, 2026)

- Maintenance release

### Compatibility

| Plugin Version | IQ Server Version | Jenkins Version | Java Runtime |
| --- | --- | --- | --- |
| 3.33.0 and higher | 144 and higher | 2.516.3 (LTS) or higher | JDK 17, 21 |
| 3.29.0 to 3.32.0 | 144 and higher | 2.479.3 (LTS) or higher | JDK 17, 21 |

## Prerequisites

The Sonatype Platform Plugin for Jenkins uses the HTTP proxy settings defined in _Manage Jenkins > Manage Plugins > Advanced_. These settings take precedence over any JVM proxy settings and are applied consistently by both Nexus Repository and IQ Server. If no Jenkins proxy settings are configured in the UI, the plugin falls back to the JVM proxy settings, for example:

```java
-Dhttp.proxyHost=127.0.0.1
-Dhttp.proxyPort=8080
-Dhttp.nonProxyHosts="*.demo"
```

To bypass the HTTP proxy server you must update the non-proxy host to include the IQ Server.

## Installation and Configuration

Go to the [Installation and Configuration](https://help.sonatype.com/en/installation-and-configuration---sonatype-platform-plugin-for-jenkins.html "Installation and Configuration - Sonatype Platform Plugin for Jenkins") page for steps to install and set up Sonatype Platform Plugin for Jenkins.

## Adding an Evaluation to a Build

_Pipeline_ refers to both [Declarative and Scripted Jenkins Pipelines](https://jenkins.io/doc/book/pipeline/).

_Project (or Job)_ refers to [a Jenkins item](https://www.jenkins.io/doc/book/glossary/#item-1), such as a Freestyle project, Multi-configuration project, or Maven project, that allows selecting an explicit _build__step_ from a drop-down menu and filling in form field values inside the build configuration.

The scan patterns applied by default are `**/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz`.

To use other patterns, a manual override of `iqScanPatterns` is required, as described in the pipeline build step below.

### Adding Pipeline Build Step

Use the following steps to add a Lifecycle Policy Evaluation build step to a pipeline build:

1. On the Pipeline project page, click **Pipeline Syntax** in the left menu to open the Snippet Generator.
2. In _Snippet Generator > Steps_, under _Sample Step_, select **nexusPolicyEvaluation: Invoke Sonatype Policy Evaluation**.
3. Fill in the [values for the policy evaluation](https://help.sonatype.com/en/sonatype-platform-plugin-for-jenkins.html#policy-evaluation-values-and-advanced-options "Policy Evaluation Values and Advanced Options").
4. Click the **Generate Pipeline Script** button.
5. Copy the generated script and paste it into the desired stage of your pipeline script.

**Example Pipeline Script**

```groovy
nexusPolicyEvaluation(
     iqApplication: 'SampApp',
     iqInstanceId: 'MyIQServer1',
     iqStage: 'build'
)
```

**Example Pipeline Script with Scan Patterns to Override Defaults**

```groovy
nexusPolicyEvaluation(
     iqApplication: 'SampApp',
     iqInstanceId: 'MyIQServer1',
     iqScanPatterns: [[scanPattern: '**/*.js'], [scanPattern: '**/*.zip']],
     iqStage: 'build',
     iqOrganization: '55040769ec08424e84049356a3362d07'
)
```

The scan patterns support exclude patterns. The exclude patterns start with a '!' character and must be specified after all other included patterns. For example, the following scan patterns will consider for evaluation all files except those under the '.git' directory:

```groovy
iqScanPatterns: [[scanPattern: '**'], [scanPattern: '!.git/**']]
```

**Example Pipeline Script Overriding Most Advanced Options**

```groovy
nexusPolicyEvaluation(
     advancedProperties: 'test=value',
     enableDebugLogging: true,
     failBuildOnNetworkError: true,
     failBuildOnScanningErrors: true,
     iqApplication: selectedApplication('sandbox-application'),
     iqInstanceId: 'MyIQServer1',
     iqModuleExcludes: [[moduleExclude: '**/module-2-exclude/module.xml'], [moduleExclude: '**/module-1-exclude/module.xml']],
     iqScanPatterns: [[scanPattern: '**/other/*.jar'], [scanPattern: '**/special/*.jar']],
     iqStage: 'build',
     jobCredentialsId: 'iq-server-localhost'
)
```

### Adding Project Step

Use the following steps to add a Lifecycle Policy Evaluation build step to a project:

1. On the project page, click **Configure** in the left menu.
2. Click **Build Steps**.
3. Click the **Add Build Step** button.
4. Select **Invoke Sonatype Policy Evaluation**.
5. Fill in the [values for the policy evaluation](https://help.sonatype.com/en/sonatype-platform-plugin-for-jenkins.html#policy-evaluation-values-and-advanced-options "Policy Evaluation Values and Advanced Options").
6. Click **Save**.

### Policy Evaluation Values and Advanced Options

- **IQ Instance:** Select an IQ Server that will be used to run the policy evaluation.
- **Stage**: Select _Develop_, _Source_, _Build_, _Stage Release_, _Release_, or _Operate_. This controls the stage the policy evaluation is run against on the IQ Server. Only the stages you are licensed to appear in the list.

**Note**

The severity of the IQ Server Policy Actions for a Stage determines the final build result. A Warn action equates to an UNSTABLE build. A Fail action equates to a FAILURE.
- **Organization (optional):** Select an organization from the list. If automatic application creation is enabled and the application does not exist, it will be created under the selected organization. If both the application and the organization IDs are provided, and the application already exists under a different organization, the evaluation process stops with an error message. This mechanism is in place to prevent accidental configurations, which could unintentionally alter the evaluation history of existing applications.
- **Application**: Select an application from the list of available IQ Server applications. This determines the policy elements (policies, labels, and license threat groups) to associate with this build and is managed via the IQ Server. An application can also be specified that is not on the list. If automatic application creation is enabled, an application with the specified ID will automatically be created if it does not already exist in the IQ Server.
- **Scan Targets:** The plugin is configured by default to scan the following targets within your workspace: `**/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz`. Any special non-archive files like manifests may incur special handling depending on the version of the plugin used. Each scan target field takes an Apache Ant-styled pattern (i.e. \*\*/\*.js). Supplying custom scan targets will limit scanning to only those files matching the scan targets.
- **Reachability Analysis:** If enabled, this feature will identify vulnerable components that can be reached by executing the application.
- **Advanced Options:**
  - **Module excludes in workspace:** Here you can exclude any of the `module.xml` files from evaluation. Module Excludes takes Apache Ant-styled patterns (i.e. \*\*/sonatype-clm/module.xml). Once you define your module excludes, click **Add**.

**Note**

Module Excludes is only for excluding `module.xml` files generated by Sonatype CLM for Maven and is not an option for excluding scan targets.
  - **Fail build when unable to communicate with IQ Server:**`failBuildOnNetworkError` - Enabling the option will fail the build when the IQ Server is unreachable.
  - **Fail build when there are scanning errors:**`failBuildOnScanningErrors` - Enabling this option will fail the build when there are scanning errors, e.g. malformed files that could not be read. Otherwise, the build status will be `UNSTABLE`.
  - **Unstable build when there are scanning warnings:**`unstableBuildOnScanningWarnings` - Disabling this option will mark the Jenkins job as `SUCCESS` instead of `UNSTABLE` if the policy evaluation has alerts with a warn action. The option is enabled by default.
  - **Use job specific credentials:** This allows overriding the global credential configuration with job-specific authentication credentials. Select any of the existing credentials or click **Add** and select **Jenkins** to open the Jenkins Credentials Provider pop-up.
  - **Enable debug logging:** Increase the verbosity of the plugin-specific job logging to aid in diagnosing scanning problems or verifying scanning configuration.
  - **Advanced properties:** In a few cases, Sonatype support may provide additional parameters to the plugin using this input.

## Evaluating Docker Images

Use the container prefix in the scan pattern to scan the docker images you want to scan.

```
nexusPolicyEvaluation iqApplication: 'appId', iqInstanceId: 'MyIQServer1', iqScanPatterns: [[scanPattern: 'container:namespace/image:image-tag']], iqStage: 'build'
```

## Reviewing Evaluation Results

Once the build is complete, a summary is shown on the project page. The three boxes (red, orange, and yellow) located below the link give you counts for policy violations and are based on the associated severity (critical, severe, and moderate).

A historical graph is also shown to indicate policy health over time.

Additionally, a build report is available within Jenkins by clicking the _IQ Build Report_ in the left-hand navigation. This build report shows which components caused a 'warn' or 'fail' action on a particular build.

### Returned Pipeline Stage Statuses

When an evaluation is performed by the plugin, the stage status depends on the configured policy actions.

- Jenkins shows `unstable` for the build when the policy action is set to `WARN`
- Jenkins shows `failed` for the build when the policy action is set to `FAIL`
- When the policy action is set to `No Action`, discovered policy violations will have no effect on the Jenkins build state.

Use the variable `currentBuild.result` to examine the value returned within the pipeline script.

### Using Policy Evaluation Results

Utilizing the Sonatype for Jenkins plugin provides full component intelligence and the ability to run policy against your application. Jenkins pipelines let you invoke a build step as part of the build process and use the results for complex workflows. For example, objects returned from a build pipeline step can be used to provide feedback in the application about the process of an evaluation.

### Reachability Analysis

See [Reachability Analysis with Jenkins](https://help.sonatype.com/en/reachability-analysis-with-jenkins.html "Reachability Analysis with Jenkins") for how to enable Reachability in Pipeline/Multi-branch jobs, including required plugin versions, the parameters and Pipeline snippet, and the entry point strategy with tips for narrowing scope via namespaces.