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.
Link 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:
- Click Application Links (under 'Settings') in the Bitbucket Server admin area.
- Enter the URL for the JIRA Software instance you want to link to and click Create new link.
- 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).
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 Access authentication types.
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.
- 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.
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).
See Link Atlassian applications to work together for more details.
Update an existing link to use OAuth
You may need to update an existing application link to use OAuth authentication when:
- you upgrade an Atlassian application to a version that uses version 5.2, or later, of application links. See the Application links version matrix.
- the existing link uses Trusted Applications authentication, but your team can't see summary information from a developer tool such as Bitbucket Server in the Development panel in Jira Software issues.
- an existing application link uses OAuth, but your team can't see the details dialogs for the Development panel in Jira Software issues.
- you use a plugin that requires the OAuth authentication type.
Here's how to do that in Jira Software, but the process is much the same for other Atlassian server products:
Begin in the local application
Go to the 'Configure Application Links' page in the admin area of the local application.
You may see a DEPRECATED lozenge beside links that need to be updated.
In the 'Edit' dialog, set the local authentication for the link under 'Connections':
Choose either:
- OAuth where both applications have different userbases.
- OAuth (impersonation) if both applications share the same userbase, typically managed with an external directory using LDAP.
Make sure that that the authentication matches for the local and remote ends of both the incoming and outgoing directions.
Click Save changes.
Now, in the remote application
Go to the 'Configure Application Links' page in the admin area of the remote application. Choose the instructions column here that matches the UI you see (they both achieve the same result):
In the 'Edit' dialog, set the local authentication for the link under 'Connections':
Choose either:
- OAuth where both applications have different userbases.
- OAuth (impersonation) if both applications share the same userbase, typically managed with an external directory using LDAP.
Make sure that that the authentication matches for the local and remote ends of both the incoming and outgoing directions.
Click Save changes.
In the 'Configure' dialog, click Outgoing Authentication and then the OAuth tab:
Now, select Enable 2-Legged OAuth, assuming that the applications have different userbases.
Optionally, select Enable 2-Legged OAuth with impersonation, if both applications share the same userbase, typically managed with an external directory using LDAP.
Click Update.
Now, click Incoming Authentication and then the OAuth tab:
Now, select Enable 2-Legged OAuth, assuming that the applications have different userbases.
Optionally, select Enable 2-Legged OAuth with impersonation, if both applications share the same userbase.
Click Update.
Note that:
Users who can see summarized data in the Jira Software Development panel may not have permission to see all the information that contributed to those summaries and that 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.
Your team members must have the 'View Development Tools' permission in Jira Software to see the Development panel for an issue.
Application links between Jira Software and Atlassian developer tools (Bitbucket Server, Bamboo, Crucible, Fisheye) must have Trusted Applications and Basic Access authentication disabled.
If you run an application on port 443, you must use a valid SSL certificate (which is not self-signed) to get the full functionality available.
See OAuth security for application links for more details.
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 is integrated with JIRA Software versions earlier than 5.0.
- Transitioning issues requires OAuth authentication. If only Basic Access authentication is used for the application link, 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 will be displayed. See Making a primary link for links to the same application type.
Link Bitbucket Server with JIRA Software Cloud
There are port restrictions, and other considerations, when linking Bitbucket Server with JIRA Software Cloud.
Your local server must use a valid SSL certificate, and it must be accessible on port 80 or 443. For more information, see this Atlassian Cloud documentation.
If you have a internet-facing firewall, make sure to allow the IP range used by Atlassian to reach your internal network. For up-to-date information on that, see Atlassian cloud IP ranges and domains.
Troubleshoot integration with JIRA Software
There are a few situations where the integration of Bitbucket Server with JIRA Software can produce an error or may not function as expected:
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.
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 will be 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. See this issue: STASH-2470 - Getting issue details... STATUS
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 recognize 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 authentication.
Still having problems?
See Troubleshooting JIRA Software Integration for more information specifically related to JIRA Software and Bitbucket Server.
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.