Troubleshooting JIRA Integration

Still need help?

The Atlassian Community is here for you.

Ask the community

Bitbucket Server - JIRA Integration Checklist

If Bitbucket Server 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 Bitbucket Server.
JIRA 4.3.0 - 5.0.3 requires upgrading to a special version of the JIRA Fisheye/Bitbucket Server plugin in, see JIRA Fisheye-Bitbucket Server Plugin compatibility for details.
JIRA 4.2.x and below do not support Bitbucket Server 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 Bitbucket Server and JIRA?

Full integration between Bitbucket Server and JIRA requires a reciprocated (two-way) application link between Bitbucket Server and JIRA.

See Linking Bitbucket Server 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:

  1. Go to Bitbucket Server, click Administration > Application Links and make sure there is an application link entry for your JIRA server.
  2. Go to JIRA, click Administration > Application Links and make sure there is another application link entry pointing back to your Bitbucket Server instance.

Can your JIRA server and Bitbucket Server instance see each other on the network?

To check your applications can see each other, again go to Bitbucket Server, 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 Bitbucket Server 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 Bitbucket Server 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 Bitbucket Server instance. 

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 Bitbucket Server 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.

To check: 

  1. Go to the Bitbucket Server "Administration" screen, select "Application Links"
  2. Note the type of authentication in the "Incoming Authentication" and "Outgoing Authentication" columns for your JIRA application link
  3. 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.
  4. Go to the JIRA "Administration" screen, select "Application Links" and check that the "Outgoing Authentication" column matches the "Incoming Authentication" from the Bitbucket Server administration, and vice-versa
  5. 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 Bitbucket Server instance's IP address in the Trusted Applications configuration for your Bitbucket Server application link in JIRA. See Configuring Trusted Applications Authentication for more details.

Have you pushed to your Bitbucket Server repository since creating your Application Links?

For performance reasons, Bitbucket Server 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, Bitbucket Server 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 Bitbucket Server integration features in JIRA piggyback off the JIRA Fisheye plugin. To check whether the plugin is enabled:

  1. Go to JIRA, click Administration > Manage Add-Ons (or Administration > Plugins in earlier JIRA versions) 
  2. Click Show System Plugins
  3. Check that the Fisheye Plugin is marked enabled
  4. 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 Bitbucket Server uses to look for issue key. See https://confluence.atlassian.com/display/BitbucketServerKB/Integrating+with+custom+JIRA+issue+key for details.

Do you have any custom plugins installed?

Versions of Bitbucket Server 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 Bitbucket Server and following the guide at https://confluence.atlassian.com/display/BitbucketServerKB/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:

Otherwise raise an issue in the Bitbucket Server project and our legendary support staff will help you out.

 

Last modified on Nov 15, 2018

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.