Jira integration

This feature is in alpha and is currently available in Enterprise and Team plans. If you are interested in trying it out, please contact moc.ecruosranostcatnoc

Integrate SonarQube Cloud directly into your Jira workflow by transforming SonarQube issues into actionable Jira work items.

Setting up your Jira integration

Before you can create Jira work items in SonarQube Cloud, you need to set up your Jira integration on the organization and project levels, and have the right permissions.

Permissions

1. To set up your Jira integration for your SonarQube organization you need the Administer Organization permissions. Go to Your Organization > Administration > Permissions and select the Administer Organization checkbox for specific users or groups.
2. To connect your SonarQube project with a Jira project you need the Administer project permissions. Go to Your Project > Administration > Permissions and select the Administer checkbox for specific users and groups.

Binding your organization with Jira

First, you have to bind Jira to your organization before you can bind it to individual projects

1. Go to Your Organization > Administration > Organization settings > Jira
2. Click Connect. You will be redirected to the Atlassian authorization page for 3rd party vendors and follow the instructions. If you have multiple Jira instances, make sure to select the right instance.
3. Click Accept to authorize the connection. 
4. Once you are redirected back to SonarQube Cloud you will see a Connected badge displayed next to Jira along with information about when the connection was established and with options to Reauthorize and delete the connection.

After the connection is established you can bind your SonarQube projects with Jira projects. See Binding your projects with Jira below.

Reauthorizing your organization with Jira

Reauthorizing your organization is non-destructive, which means that connections to all projects and issues will remain intact. 

In the unlikely event that your organization doesn’t use any features of the Jira integration for three months (for example, if there are no projects connected for a given organization), the connection to Jira will expire and will need to be reauthenticated by the organization's administrator.

Deleting your organization's connection with Jira

Deleting your organization's connection with Jira removes all binding between SonarQube and Jira and related data in SonarQube Cloud. To completely remove the connection, you must revoke relevant token permissions in the Atlassian account.

By deleting the SonarQube to Jira connection, you will:

• Lose access to all Jira features in this SonarQube Cloud organization.
• Delete this organization’s project to Jira project connections.
• Disconnect all SonarQube issues from Jira work items. 

Binding your project with Jira

After connecting your SonarQube organization with your Jira instance you are now ready to connect your SonarQube project with a Jira project.

To bind your SonarQube project with Jira at a project level, go to Your Project > Administration > General Settings > Jira and select a Jira Project from the list. You can only bind one SonarQube project to one Jira project. 

1. Click Connect to open the connection modal.
2. In the modal, select a Jira project from a dropdown list. A maximum of 1,000 items is available. Use the search option to quickly find a specific project.
3. Choose the work types that you can push from SonarQube to Jira.
4. Click Connect. Your connection is now saved and you should see the confirmation on the page.

The configuration might not support all of your Jira project's mandatory fields. The following is a list of supported mandatory fields:

• Summary
• Description
• Reporter

Jira work types that have other mandatory fields associated with them are not supported and are disabled in SonarQube. You can either remove these mandatory fields in Jira or choose a supported work type in SonarQube. At least one supported Jira work type is required to save the configuration.

Once your binding between SonarQube project and Jira project is created you will see the connection details along with options to edit or delete the project binding.

Editing your project binding with Jira

By clicking on Edit, you can change the binding of your SonarQube project by connecting it with another Jira project. Editing the binding is non destructive, meaning that all SonarQube-to-Jira connections will remain intact. To completely reset your project, you must unbind the SonarQube project with Jira by clicking the delete button.

Unbinding your project from Jira

Deleting the project binding removes all of your connections and links in the Jira project. This is a complete reset between your SonarQube project and Jira.

Jira release widget

Once you bind your SonarQube project with a Jira project, a Jira widget appears on the Main Branch Summary page.

If you operate with version-based releases in Jira, the widget will surface any open Jira tickets you have associated with the earliest release.

The widget shows the following information:

• The number of open Jira issues for a given version, regardless of whether those tickets are associated with SonarQube issues or not. Click on the issue count to view them in Jira.
• Release date
• Release version

The widget retrieves only open Jira issues from the earliest unreleased Jira version. If two or more unreleased versions have the same date or have no assigned date, the widget will select the version with the lowest release ID, which is the release that was created first.

Creating a Jira work item from a single SonarQube issue

You can create a Jira work item from a SonarQube issue or from the Issues page:

1. Click the Push to Jira button and choose a Jira work type, if more than two work types are available. The list of Jira work types depends on your Jira integration configuration and is configured by the project administrator.
2. When the process is complete the button displays a Jira work item ID along with the status label.
3. A new Jira work item will be created in your Jira project and it will open in a new tab.
4. Click on the Jira work item ID to open it on the Jira’s website.

On rare occasions, two or more concurrent Jira creation events might be triggered by multiple users simultaneously, resulting in two or more Jira work items being created at the same time.

Contents of the Jira work item

When you create a Jira work item, it includes the following information:

• Title of the SonarQube issues .
• SonarQube issue link.
• Location of the issues.
  • File path.
  • Code lines.
  • Commit hash.
  • Date the issue was introduced.
• Information about why this is an issue and how to fix it with the rule name and link.
• Impact on software quality and severity.
• The reporter for the Jira work item is the default reporter set in SonarQube organization’s Jira integration.

Disconnecting a Jira work item

You cannot delete a Jira work item from within SonarQube Cloud, but you can disconnect it by clicking on the close icon of the Jira button either within the SonarQube issues or on the Issues page. The connection with the Jira work item will be removed but the item will still exist in Jira.

Creating a Jira work item from multiple SonarQube issues

You can push multiple SonarQube issues into a single Jira work item from the project’s issues page in SonarQube.

1. Select the issues you want to include in the Jira work item.
2. Click Push to Jira at the top of the issues page to open a modal.
3. In the modal select the work type that you want to apply to the Jira work item.

SonarQube creates a Jira work item with issues that have not been previously connected to Jira. If you have selected issues that currently have a Jira connection and you want to include them in this Jira work item, you will have to disconnect them from Jira first. See Disconnecting a Jira work item section above for more information.

Troubleshooting

The following are the typical errors that might prompt you to troubleshoot the connection with Jira:

• The administrator who set up the connection has left the company and the Atlassian token has been removed.
  Solution: The new administrator has to reauthorize the Jira connection at the organizational level.
• The connection has been reauthorized with a wrong Jira instance.
  Solution: Make sure to select the correct Jira instance in the selection modal when reauthorizing the Jira connection at the organization level. SonarQube remembers previous issue-to-Jira work item connections on the project levels, but the organization has to be reauthorized to the original Jira instance for these connections to be available again.
• Some Jira work types cannot be selected on the project settings page for Jira.
  Solution: Jira work types that have other mandatory fields associated with them are not supported and are disabled in SonarQube. You can either remove these mandatory fields in Jira or choose a supported work type in SonarQube. 

Other issues:

• The Push to Jira button is not visible on the SonarQube issue page.
  Solution: After connecting your organization to a Jira instance you need to bind individual SonarQube projects to Jira projects. See Binding your project with Jira section.
• The Jira release widget does not show any insights, even though your team is operating under a version-based release cycle.
  Solution: Ensure you have releases and versions enabled in your Jira project. See more on Atlassian’s webpage.

Related pages

• Setting project permissions and visibility
• Managing the organization-related permissions