# Sonatype for Jira Cloud

Sonatype for Jira Cloud automatically creates issues in response to new violations as they occur during your policy evaluation. Prioritize and track the remediation of open-source component risk directly in your development workflow.

The Sonatype for Jira Cloud integration is available on the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1232875/sonatype-for-jira-cloud-preview?hosting=cloud&tab=overview).

## Release Notes

## Changelog

### Version 2.23.0 (July 21, 2026)
- Updated the Admin page to identify missing fields and the issue type when a policy violation webhook fails
- Added a warning above Additional Required Fields on the Project Settings page that lists any required Jira fields without a configured default value
- Significantly reduced log volume while preserving essential troubleshooting information

### Version 2.22.0 (May 25, 2026)
- Maintenance release

### Version 2.21.0 (April 30, 2026)
- Maintenance release

### Version 2.20.0 (April 23, 2026)
- Maintenance release

### Version 2.19.0 (April 08, 2026)
- Updated internal dependencies to address a security vulnerability

### Version 2.18.0 (March 20, 2026)
- Maintenance release

### Version 2.17.0 (February 18, 2026)
- Maintenance release

### Version 2.16.0 (December 19, 2025)
- Maintenance release

### Version 2.15.0 (May 14, 2025)
- Maintenance release

### Version 2.14.0 (April 01, 2025)
- Upgraded the UI kit to version 2 (internal change)
- Added Developer Priorities URL to the generated issues’ description
- General UI improvements

### Version 2.13.0 (December 09, 2024)
- Maintenance release

### Version 2.12.0 (October 08, 2024)
- Fixed handling of issue type breaking the project settings page if it was deleted after being configured

### Version 2.11.0 (July 31, 2024)
- Improved transition handling, more info in issues and bug fixes

### Version 2.10.0 (June 25, 2024)
- Minor version update

### Version 2.9.0 (May 30, 2024)
- Minor version update

### Version 2.8.0 (May 29, 2024)
- Minor version update

### Version 2.7.0 (Apr 26, 2024)
- Minor version update

### Version 2.6.0 (Apr 12, 2024)
- Minor version update

### Version 2.4.0 (Jan 24, 2024)
- Removed from Preview

### Version 2.3.0 (Dec 20, 2023)
- Preview edition - Sonatype for Jira Cloud

## Compatibility

| Plugin Version | IQ Server Version | Jira Cloud Version |
| --- | --- | --- |
| 2.3.0 and higher | 69 and higher | latest (rolling release) |

## Steps for Configuration

To perform as a Jira Cloud site admin:

1. Install Sonatype for Jira Cloud
2. Configure the integration in Jira Cloud
3. Configure the integration per project to receive tickets

To perform as IQ Server and Policy administrator:

1. Add webhook to the Jira Cloud in IQ Server
2. Set up notifications on the Lifecycle policy

## Install Sonatype for Jira Cloud

Install the integration directly from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1232875/sonatype-for-jira-cloud-preview?hosting=cloud&tab=overview)

## Configuration Requirements

- A Sonatype Lifecycle license with IQ Server version 168 or higher.
- The latest Sonatype for Jira Cloud integration installed.
- A webhook endpoint from Jira with a secured secret key.

**Warning**

The secret key will be created by your team to encrypt requests. Keep the key secret as it will have permission to send requests to add issues in your Jira instance.

## Configure Sonatype for Jira Cloud

After installing the plugin, we need the webhook to send requests to Jira:

1. In Jira, log in as an account with permission to manage applications
2. From the top navigation bar, select "Apps" and "Manage apps"
3. Select "Sonatype for Jira Cloud"
4. Fill in the secured secret key for managing webhooks
5. Add the IQ Server Base URL for report links
6. Select Submit to save the entry
7. Copy the webhook URL to configure the IQ Server webhook in a later step

## Assign Sonatype Lifecycle Applications to Jira Projects

You must assign Sonatype Lifecycle applications to your Jira projects before new violations are created as issues.

1. Navigate to your Jira project
2. Select `Project Settings`
3. From the left menu, select "Lifecycle Project Configuration"
4. Select the issue type to create violations
   1. The available options are: Task, Story, Bug, Epic
5. Select the issue aggregation method
   1. By Component - Create a subtask for each component with violations
   2. By IQ Evaluation - Create a single issue that lists all violations across all components
6. List the Lifecycle Organizations and Applications for the project
   1. Include a comma-separated list of Organizations or Application IDs from Lifecycle
   2. Select the Organizations and Applications from the drop-down when using the '_Organization and Application Summary_' webhook event type
7. Set the optional Workflow Transition state to refresh the ticket when the violations are resolved in Sonatype Lifecycle
8. Fill in the required fields based on the issue type, i.e., Reporter (the account associated with the automatically-created tickets.)

**Note**

Every time a new required field is added to the selected issue type or sub-task type, the plugin configuration has to be updated by providing a default value for the new required field. New Jira issues cannot be created unless all required fields are populated.

## Create a webhook in the Lifecycle server

The Lifecycle server webhooks are used to communicate with the plugin

1. Log into the Lifecycle server as an administrator
2. Select `Webhooks` from the `System Preferences` gear icon in the top right menu
3. Select `Add a Webhook`
4. Paste in the webhook URL from the plugin
5. Include a meaningful description to be displayed as a notification option
6. Use the same secret key entered in the plugin configuration
7. Set the event type to `Violation Alert`
8. Optionally, create a webhook with the `Organization and Application Summary` event type
   1. This event is used to populate the applications dropdown from the project configuration
9. Select `Create` to save the webhook

**Note**

The `Organization and Application Summary` webhook event may result in slow performance and potential security concerns for Lifecycle servers with hundreds of applications.

The assigning applications dropdown is only present when this webhook is configured. Instead, you will need to provide a comma-separated list of organizations and application Ids.

## Configure Notifications on Policies

Not all policy violations require a Jira ticket to be created whenever it is found. Notifications in Lifecycle are set on each policy for the stages you wish tickets to be created for. For example, creating tickets on all security-critical and security-high violations at the build stage. The following steps will need to be performed for each policy violation you will want to configure a Jira notification for.

1. Sign into an account with policy administration access permissions
2. From Orgs and Policies selection the policy to edit
3. Select _Webhook_ from the _Recipient Type_ drop-down menu
4. Select the appropriate _Webhook_ from the _Select Webhook_ drop-down menu
5. Click _Add_ to add the notification
6. Specify the stage(s) to create notifications for (build, release, etc)

|     |
| --- |
|  |

## Review violation tickets within the plugin

When Lifecycle detects violations, new issues are created on the project board with the `New` status.

Example of issue aggregation of `By IQ Evaluation`

A subtask is created for each of the components attached to the primary report scan ticket for the issue aggregation of `By Component`

The following fields are populated as follows:
- **Type**: Corresponds to the selected issue type on the mapping page.
- **Labels**: Corresponds to a selected label on the mapping page.
- **Reporter**: Corresponds to a selected reporter on the mapping page.
- **Priority**: Lifecycle threat level 10 is mapped to the highest Jira priority with the threat of 0 is mapped to the lowest priority. Additional priorities are assigned using a linear function.

| Threat Level | Jira Priority |
| --- | --- |
| 9-10 | Highest |
| 7-8 | High |
| 4-6 | Medium |
| 2-3 | Low |
| 0-1 | Lowest |

**Note**

Priority names for your organization can be different if they've been customized in Jira settings by a Jira admin.

## Supported and unsupported field types

Default values are required for mandatory fields in Jira. The plugin will ignore the unsupported fields if they are marked optional in Jira.

The supported fields are: `Number, Paragraph, Short text, Select list (single choice), Select list (multiple choices), URL, Radio, Labels`

## Logging Details

In Sonatype for Jira Cloud's logs, we only record the IQ payload from webhook events, including whether they were processed successfully and any error messages. We do not capture or store any data from Jira itself; our logging is strictly limited to IQ content and metadata automatically provided by Jira.

## Jira Integration troubleshooting tips

- Check that policy notifications are sent to the Jira webhook.
  - Jira issues are only created for new violations.
  - `No Action` is taken when the violation has already been sent to Jira.
- Verify the webhook URL matches between the Lifecycle server and Jira.
- Check the Sonatype for Jira Cloud configuration page on Jira for error messages. The message box will display the status of the last webhook received from the Lifecycle server.
- At least one application or organization needs to be mapped to the project.
- Check that the violation alerts are mapped to the correct Jira project.
- Check that the evaluation stage matches the configured webhook notification.