Linking Stash with JIRA

Linking Stash with JIRA

You can integrate Stash with one or more instances of JIRA by means of 'application links'. You set up application links either:

• during the Stash install process, using the Setup Wizard, or 
• at any time after installation, as described below.

To link Stash to a JIRA server:

1. Click Application Links (under 'Settings') in the Stash admin area.
2. Enter the URL for the JIRA instance you want to link to and click Create new link.
3. Complete the application link wizard to connect Stash to your JIRA server. You must make use of the automatic link-back from JIRA to Stash to get full integration (you'll need JIRA system administrator global permission for that).

When you create a new application link between JIRA and an instance of Stash, 2-legged (2LO) and 3-legged OAuth (3LO) are enabled by default. 2LO is required for information from Stash to be included in the summaries in the Development panel of the JIRA issue; 3LO checks that a JIRA user has authenticated with Stash before they get to see the information in any of the details dialogs. 

An older application link between JIRA and Stash will need to have 2LO authentication explicitly enabled.

Note that:

• The following system plugins must be enabled in Stash. These are bundled and enabled by default in Stash 2.10 (and later):

  • Atlassian Navigation Links Plugin (com.atlassian.plugins.atlassian-nav-links-plugin) 
  • Stash Dev Summary Plugin (com.atlassian.stash.stash-dev-summary-plugin).

• Users who can see summarized data in the Development panel may not have permission to see all the information that contributed to those summaries and which is visible in the details dialogs (for example, for branches, commits and pull requests). That is, the details dialogs respect the access permissions that users have in the connected applications.

• When Stash 2.10 or later is linked with JIRA 6.2 or later, you won't see the Source tab at the bottom of the JIRA View Issue screen any more. 

• Application links must have Trusted Applications and Basic Access authentication disabled. The Development panel in the JIRA issue view only supports OAuth authentication.

• Stash only begins scanning commit messages for JIRA issue keys on the first push after you created the application link to JIRA – the scan may take a short time.
• Integrating Stash with JIRA may require an upgraded version of the FishEye/Stash plugin in JIRA. See JIRA FishEye-Stash Plugin compatibility for details about upgrading the JIRA FishEye/Stash plugin, and for download links to the upgraded plugin versions.

More detailed information about application links can be found on Configuring Application Links.

Restrictions for JIRA integration

• The display of details for JIRA issues, for example when viewing a pull request, relies on the JIRA 5.0 REST API. Issue details are not displayed when Stash in integrated with JIRA versions earlier than 5.0.
• Transitioning JIRA issues requires OAuth AppLinks. If only a Basic Auth applink is set up, users will be able to view issue details, but will not be able to transition issues.
• JIRA permissions are respected, so a user who is not permitted to transition an issue in JIRA will not see the transition buttons in Stash.
• If Stash is linked with multiple JIRA instances and the JIRA projects happen to have the same key, only the issue from the instance marked as Primary  will be displayed. See Making a primary link for links to the same application type.

Restrictions when linking Stash with JIRA Cloud

In addition, there are port restrictions, and other limitations, when linking Stash with JIRA Cloud. Pleases see Integrating JIRA Cloud with Stash.

Known issues with JIRA integration

We have tried to make the integration of JIRA with Stash as straightforward as possible. However, we are aware of the following issue:

• There is no checking for project or issue-key validity; Stash may link to issues that do not actually exist:  STASH-2470 - Getting issue details... STATUS

We apologise for the inconvenience. Please watch the issue to keep track of our progress.

Troubleshooting integration with JIRA

There are a few scenarios where the integration of Stash with JIRA can produce an error:

The application link is misconfigured

This can result if authentication for the application link has not been set up. See Troubleshooting JIRA Integration.

You don't have permission to access the JIRA project

If you don't have permission to access the JIRA project then Stash is unable to display issues.

The JIRA server is of an unsupported version

Stash can integrate with JIRA 4.3.x, or later. Some features require higher versions of JIRA to function properly. See Integrating Stash with Atlassian applications for details.

The JIRA issue key is invalid

Stash doesn't check for invalid issue keys, such as UTF-8. An error will result if Stash tries to connect to an issue that doesn't exist.

The JIRA issue keys are of a custom format

Stash assumes that JIRA issue keys are of the default format (that is, two or more uppercase letters ([A-Z][A-Z]+), followed by a hyphen and the issue number, for example STASH-123). By default, Stash will not recognise custom JIRA issue key formats. See Using custom JIRA issue keys with Stash for details.

The Application Link is created with OAuth only without the option to create a link using Trusted Applications

Stash allows a user with global permissions of "Administrator" to create an OAuth only application link. You need to log in with a user having "System Administrator" privileges to create an application link using Trusted Applications.