Linking Bitbucket Server with JIRA

See JIRA integration for a description of all the integrations you get when Bitbucket Server is linked with JIRA Software.

You can also use JIRA Software for delegated user management. See External user directories.

This page describes how to link Bitbucket Server to JIRA Software.

Linking Bitbucket Server with JIRA Software

On this page

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

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

To link Bitbucket Server to a JIRA Software server:

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

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

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

Click here to see how to enable 2-legged OAuth...

An existing application link between JIRA Software and Bitbucket Server (that perhaps used Trusted Apps authentication) needs to have 2-legged authentication (2LO) enabled for both outgoing and incoming authentication, so that information from Bitbucket Server can be included in the Development panel summaries within JIRA Software.

When updating an older application link to use OAuth, 3-legged authentication is applied by default, but you need to explicitly enable 2LO. Enable 2-legged authentication for the application link from within JIRA Software as follows:

  1. Go to the admin area within JIRA Software and click Add-ons > Application Links
  2. Click Edit for the app link with the Bitbucket Server instance.
  3. For both Outgoing Authentication and Incoming Authentication:
    1. Click OAuth
    2. Check Allow 2-legged OAuth.
    3. Click Update.

The application link update process will involve logging you into Bitbucket Server for a short time to configure that end of the link, before returning you to JIRA Software.

Note that:

  • Atlassian only recommends using OAuth authentication for application links, because of the greater security inherent with that protocol. We no longer recommend the Trusted Applications and Basic authentication types.

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

    • Atlassian Navigation Links Plugin (com.atlassian.plugins.atlassian-nav-links-plugin) 
    • Bitbucket Server Dev Summary Plugin (bitbucket-jira-development-integration-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.

  • Users must have the 'View Development Tools' permission within JIRA Software to see the Development panel within an issue.
  • When Bitbucket Server 4.0 or later is linked with JIRA Software 6.2 or later, you won't see the Source tab at the bottom of the View Issue screen any more. 

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

  • Bitbucket Server only begins scanning commit messages for issue keys on the first push after you created the application link to JIRA Software – the scan may take a short time.

More detailed information about application links can be found in the Application Links user guide.

Restrictions for JIRA Software integration

  • The display of details for JIRA Software issues, for example when viewing a pull request, relies on the JIRA 5.0 REST API. Issue details are not displayed when Bitbucket Server in integrated with JIRA Software versions earlier than 5.0.
  • Transitioning 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 Software permissions are respected, so a user who is not permitted to transition an issue will not see the transition buttons in Bitbucket Server.
  • If Bitbucket Server is linked with multiple JIRA Software instances and the projects happen to have the same key, only the issue from the instance marked as Primary (tick) will be displayed. See Making a primary link for links to the same application type.

Restrictions when linking Bitbucket Server with JIRA Software Cloud

There are port restrictions, and other limitations, when linking Bitbucket Server with JIRA Software Cloud. Please see Integrating with developer tools.

Known issues with JIRA Software integration

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

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

Please watch the issue to keep track of our progress.

Troubleshooting integration with JIRA Software

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.

There are a few scenarios where the integration of Bitbucket Server with JIRA Software can produce an error or may not function as intended:

Unable to see the Development panel within an issue

You must have the 'View Development Tools' permission in JIRA Software to see the Development panel. See Managing Global Permissions.

The application link is misconfigured

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

You don't have permission to access the project

If you don't have permission to access the project within JIRA Software then Bitbucket Server is unable to display issues.

The JIRA Software server is of an unsupported version

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

The issue key is invalid

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

The issue keys are of a custom format

Bitbucket Server assumes that 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 TEST-123). By default, Bitbucket Server will not recognise custom issue key formats. See Using custom JIRA issue keys with Bitbucket Server for details.

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

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

 

Last modified on Oct 6, 2015

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.