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?

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 Link Bitbucket 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?

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 'bitbucket' installed." when trying to create an application link
• <REPO_NAME> is already indexing, ignoring second indexing request
• Application Bitbucket Server seems to be offline in JIRA after creating an application link to Bitbucket Server
• Application Link (Source tab via OAuth) fails in JIRA after Bitbucket Server upgrade
• Application Link between Bitbucket Server 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
• Bitbucket Server does not link commit to JIRA after setting custom JIRA issue key regex
• Bitbucket Server HTTPS request is redirecting back to HTTP URL during application links creation
• 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 Bitbucket Server to JIRA for User Management Fails
• Error while integrating Bitbucket server with other Atlassian products
• Failing to push into repository or managing branch permissions after upgrade
• Getting "Invalid OAuth credentials" when registering a Jira Software Cloud site in Bitbucket Data Center
• Git Commits Are Not Linking to JIRA Tickets Due to Corrupted Indexes
• Incorrect Bitbucket URL displayed in Jira Cloud after creating Bitbucket Server staging environment from production
• Integrating with custom JIRA issue key in Bitbucket Server
• Issues column on Commit tab of repositories does not show link to JIRA issue keys
• Jira issue keys do not display the issue in Bitbucket Server
• 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 Bitbucket Server (or vice-versa)
• Trusted Application Authentication IPv6 Exception
• User cannot create issues in Jira from Bitbucket Server/Datacenter after upgrade to Jira 9.x

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