Link Bitbucket with Jira
See Jira integration for a description of all the integrations you get when Bitbucket Data Center and Server is linked with Jira.
You can also use Jira Software for delegated user management. See External user directories.
This page describes how to link Bitbucket to Jira Data Center, Server, and Cloud using Application Links as well as connecting Bitbucket Data Center with Jira Software Cloud using OAuth.
On this page
Link Bitbucket with Jira
You can integrate Bitbucket with one or more instances of Jira by means of 'application links'. You set up application links either:
- during the Bitbucket install process, using the Setup Wizard, or
- at any time after installation, as described below.
To link Bitbucket to a Jira server:
- Click Application Links (under 'Settings') in the Bitbucket admin area.
- Enter the URL for the Jira site you want to link to and click Create link.
- Complete the application link wizard to connect Bitbucket to your Jira. You must make use of the automatic link-back from Jira to Bitbucket to get full integration (you'll need System Admin global permission for that).
Note that:
- Bitbucket only begins scanning commit messages for issue keys on the first push after you created the application link to Jira – the scan may take a short time.
- Jira permissions are respected, so a user who is not permitted to transition an issue will not see the transition buttons in Bitbucket.
If Bitbucket is linked with multiple Jira sites and the projects happen to have the same key, you can view issues from all linked Jira sites, To do this, select the issue key in Bitbucket. The relevant issues will display in the issue dialog.
If you configure project links, the first issue in the dialog will be the one from a selected Jira instance. Learn how to configure project links across your applications.
- If Bitbucket is linked with multiple Jira sites 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.
The following system plugins must be enabled in Bitbucket. These are bundled and enabled by default in Bitbucket:
- Atlassian Navigation Links Plugin (com.atlassian.plugins.atlassian-nav-links-plugin)
- Bitbucket Dev Summary Plugin (bitbucket-jira-development-integration-plugin).
See Link Atlassian applications to work together and OAuth security for application links for more details.
Link Bitbucket with Jira Software Cloud
If your Bitbucket instance is behind a firewall, we recommend that you use an application tunnel to link Bitbucket with Jira Software Cloud. Application tunnels are available for Bitbucket 6.9 and later. Learn more about application tunnels
If you're unable to use an application tunnel:
- 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 an 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.
Application Links and OAuth connections
To fully benefit from how data is shared between Jira Software Cloud and Bitbucket, it’s helpful to configure both an Application Link and OAuth credential. Bitbucket requests data from Jira using AppLinks. Adding an OAuth connection brings more Bitbucket into Jira.
Application link is recommended
An additional application link brings more benefit to Bitbucket and enables the features listed below. In this case, you only need to allow incoming connections to your network while creating the application link. Once the link is authorized, you can close these connections on your firewall and the link will still work.
Features you get with an Applink
- Viewing issue information in pull requests.
- Viewing issues on the Bitbucket home page.
- Mentioning issues in pull request comments.
- Creating issues from pull request comments.
Features you get with OAuth
- Transitioning issues to different statuses from Bitbucket.
- Viewing deployment information (related smart commits, branches, commits, pull requests) in Jira.
Integrate with Jira Software Cloud using OAuth
Integrate with Jira Software Cloud to enable Bitbucket Data Center to send it development info such as branches, commits, and pull requests, as well as to gain access to automation and reporting features in Jira Software Cloud, like:
calculating Cycle time metrics - the time that you take work to get from the first commit on a branch to production.
linked Bitbucket repositories are displayed in the Jira Software Cloud's code tab for quick and easy access.
triggering Automation for Jira events - these include Branch created, Commit created, Pull request created, Pull request declined, and Pull request merged. If you haven't linked your Jira and Bitbucket accounts, you'll be prompted to do so the first time you use these triggers.
To begin, you must be a system admin for Bitbucket as well as a site admin for Jira Software Cloud. To integrate, first, create OAuth credentials in Jira Software Cloud and then use them to register your Bitbucket instance.
Step 1: Create OAuth credentials in Jira Software Cloud
- Navigate to Jira home > Jira settings > Apps.
- Select OAuth credentials (under Atlassian Marketplace in the side navigator).
- Select Create new credentials.
- Provide the following details:
| Field | Description |
|---|---|
| App name | Any name that describes your Bitbucket instance. This could be "Bitbucket" if your company has a single instance. If your company has multiple instances of Bitbucket, we suggest using the hostname of the server. Example: bitbucket.mycompany.com |
| Server base URL | Your specified Bitbucket base URL. (Value used from the previous line) |
| Logo URL | A URL to the Bitbucket logo, which will be used as an icon in the list of credentials: |
| Permissions (required) | Allows creation of a key for development information. Example: Select "Deployments", "Builds", and "Development information". |
| Create Branch URL Template | This URL allows the Create branch action shortcut. The template contains information that you provide while creating a branch between your Jira issue and the dev tool by inserting an issue key. |
5. Select Create.
For more information on OAuth credentials in Jira Software Cloud, see their Integrate with self-hosted tools using OAuth documentation.
Step 2: Register a Jira Software Cloud site in Bitbucket
To register a Jira Software Cloud site:
- In the Bitbucket Data Center Administration area, select Jira Cloud Integration (under System).
- Select Register site.
- Complete the form using the OAuth credentials you created in Jira Software Cloud by providing the following details:
| Field | Description |
|---|---|
| Site name | Any name that describes your Jira Software Cloud site to users. This could be “Jira” if your company only uses a single site. If your company has multiple Jira sites, we suggest using the hostname of the site. Example: mycompany.atlassian.net |
| Site URL | The site URL of your Jira Software Cloud site. Example: https://mycompany.atlassian.net/ |
| Client ID | Copied from Jira Software Cloud OAuth credentials page. |
| Secret | Copied from Jira Software Cloud OAuth credentials page. |
4. Select Submit.
Step 3: Remove duplicate development info
To eliminate duplicate development information from both the application link and OAuth:
- In Jira Cloud, navigate to Administration (Settings cog) > Products > Application links tab.
- Select More actions ... next to your Bitbucket application link.
- Select Smart Commits and toggle off View development tool data.
Troubleshoot integration with Jira Software
There are a few situations where the integration of Bitbucket with Jira 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 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 then Bitbucket will be unable to display issues.
The issue key is invalid
Bitbucket doesn't check for invalid issue keys, such as 'UTF-8'. An error will result if Bitbucket 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 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 will not recognize custom issue key formats. See Using custom Jira issue keys with Bitbucket Server for details.
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.
Troubleshoot integration with Jira Software Cloud
Remove duplicate development info
If you're seeing duplicate development information, make sure you've toggled off View development tool data in Smart Commits.