Troubleshooting JIRA Integration
Stash - JIRA Integration Checklist
If Stash and JIRA aren't playing nicely together, check the following list of questions to see if any of them apply to you.
Are you using a supported version of JIRA?
|JIRA 5.0.4 and above
|integrates straight out-of-the-box with Stash.
|JIRA 4.3.0 - 5.0.3
|requires upgrading to a special version of the JIRA FishEye/Stash plugin in, see JIRA FishEye-Stash Plugin compatibility for details.
|JIRA 4.2.x and below
|do not support Stash integration. You will need to upgrade to a newer version of JIRA.
Have you tried our dedicated Application Links Troubleshooting guide?
Have a look through the Application Links Troubleshooting Guide - This is a purpose made guide catered for solving all Application Link specific issues, if you're receiving any type of error with Application Links this guide should be capturing a solution for it.
Have you created a two-way application link between Stash and JIRA?
Full integration between Stash and JIRA requires a reciprocated (two-way) application link between Stash and JIRA.
See Linking Stash with JIRA for instructions on how to create an application link. For full integration you must check the box marked " Also create a link from '<name of your JIRA server>' back to this server.", enter your JIRA administrator credentials and then select your user base scenario to configure authentication.
If you think you've already set up application links in both directions, you can check by doing the following:
- Go to Stash, click Administration > Application Links and make sure there is an application link entry for your JIRA server.
- Go to JIRA, click Administration > Application Links and make sure there is another application link entry pointing back to your Stash server.
Can your JIRA server and Stash server see each other on the network?
To check your applications can see each other, again go to Stash, click Administration > Application Links and check that there are no warnings at the top of the page. If you see a message similar to:
"Application 'JIRA Server' seems to be offline. Click here to Relocate."
it means that Stash can no longer communicate with JIRA using the URL that was used when creating the application link.
- If the JIRA server has moved you'll need to click the 'Relocate' link and go through the Relocation wizard.
- If you think the URL is correct you should check your network configuration and ensure that your JIRA server is running.
After confirming Stash can see JIRA, you should then go to JIRA, click Administration > Application Links and check that there are no warnings for the application link targeting your Stash server.
If there are no warnings on either Application Links configuration page, your servers can see each other.
Are your application links appropriately authenticated?
You must use an appropriate authentication mode (OAuth or Trusted Applications) for your application links. Trusted Applications can only be used if both of your servers are backed by the same user base (usually a Crowd or LDAP server, or when Stash is treating JIRA as a user server https://confluence.atlassian.com/display/JIRA044/Allowing+Other+Applications+to+Connect+to+JIRA+for+User+Management). If you have different sets of users in each server (or you're unsure) you should use OAuth.
- Go to the Stash "Administration" screen, select "Application Links"
- Note the type of authentication in the "Incoming Authentication" and "Outgoing Authentication" columns for your JIRA application link
- If it says the type is "none" for either incoming or outgoing, press Configure then "Incoming Authentication" or "Outgoing Authentication" and choose either OAuth or Trusted Applications, as discussed above.
- Go to the JIRA "Administration" screen, select "Application Links" and check that the "Outgoing Authentication" column matches the "Incoming Authentication" from the Stash administration, and vice-versa
- If the type is incorrect or "none", modify the configured incoming / outgoing authentication as per step 3.
Note: if you are using Trusted Applications you will need to whitelist your Stash server's IP address in the Trusted Applications configuration for your Stash application link in JIRA. See Configuring Trusted Applications Authentication for more details.
Have you pushed to your Stash repository since creating your Application Links?
For performance reasons, Stash only starts scanning commit messages for JIRA issue keys after you've created a link to your JIRA server. On the first push after creating an application link, Stash will walk through your entire repository history, which may take a short period of time. After this process has completed, issue keys from your commit messages should show up in the Issues column on the commit list.
Have you granted users the View Issue Source Tab (formerly known as View Version Control) permission in JIRA?
Only users with the View Issue Source Tab (JIRA 5.2+) or View Version Control (JIRA 5.1.1 and below) permission can view the Source tab in JIRA. See https://confluence.atlassian.com/display/JIRA/Managing+Project+Permissions for information on how to configure JIRA permissions.
Are your servers date/time synchronized?
Unsynchronized server times can break authentication. See CertificateTooOldException when Configuring Trusted Applications Authentication on an application link for details.
Is the JIRA FishEye plugin enabled in JIRA?
Some of the Stash integration features in JIRA piggyback off the JIRA FishEye plugin. To check whether the plugin is enabled:
- Go to JIRA, click Administration > Manage Add-Ons (or Administration > Plugins in earlier JIRA versions)
- Click Show System Plugins
- Check that the FishEye Plugin is marked enabled
- Ensure that all the required plugin modules are enabled
Are you using a custom issue key format in JIRA?
If you're using a custom project key format in JIRA (as described in https://confluence.atlassian.com/display/JIRACOM/Configuring+Project+Keys) you will need to configure the regular expression Stash uses to look for issue key. See https://confluence.atlassian.com/display/STASHKB/Integrating+with+custom+JIRA+issue+key for details.
Do you have any custom plugins installed?
Versions of Stash prior to version 1.2.3 could experience issue key indexing problems if a plugin indexer threw an exception during the indexing process. Try upgrading to a newer version of Stash and following the guide at https://confluence.atlassian.com/display/STASHKB/Git+Commits+Are+Not+Linking+to+JIRA+Tickets+Due+to+Corrupted+Indexes to repair your repository index if symptoms persist.
Still not working?
Having trouble integrating your Atlassian products with application links?
We've developed a guide to troubleshooting application links, to help you out. Take a look at it if you need a hand getting around any errors or roadblocks with setting up application links.
Failing that check out these child articles of this page to see if there are any that match the symptoms you're seeing:
- "There is no application type 'stash' installed." when trying to create an application link
- <REPO_NAME> is already indexing, ignoring second indexing request
- Application Link (Source tab via OAuth) fails in JIRA after Stash upgrade
- Application Link between Stash and JIRA fails due to systems clock not being synchronized
- Application Link fails with No application link found with the id
- Application Link Fails with the string error on a red banner
- Application Stash seems to be offline in JIRA after creating an application link to Stash
- Can't create Application Links. No response was received from the URL you entered
- Can't display issues
- Capabilities Warning Applications with flagged capabilities may be offline or older versions
- CertificateTooOldException when Configuring Trusted Application Link
- Connecting Stash to JIRA for User Management Fails
- Failing to push into repository or managing branch permissions after upgrade
- Git Commits Are Not Linking to JIRA Tickets Due to Corrupted Indexes
- Issues column on Commit tab of repositories does not show link to JIRA issue keys
- JIRA issue Source tab displays No related source found
- JIRA Source Tab Not Working
- OAuth is the only one tab that is displayed for an Application Link
- Oracle exception when creating AppLinks setCharacterStream
- Problem creating an Application Link from JIRA to a HTTPS Stash (or vice-versa)
- Stash does not link commit to JIRA after setting custom JIRA issue key regex
- Stash HTTPS request is redirecting back to HTTP URL during application links creation
- Trusted Application Authentication IPv6 Exception
Otherwise raise an issue in the Stash project and our legendary support staff will help you out.