Link Bitbucket with Jira

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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:

  1. Click Application Links (under 'Settings') in the Bitbucket admin area.
  2. Enter the URL for the Jira site you want to link to and click Create new link.
  3. 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, 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

There are port restrictions, and other considerations, when linking Bitbucket with Jira Software Cloud using Application Links. 

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.

  • 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

  1. Navigate to Jira home > Jira settings > Apps.
  2. Select OAuth credentials (under Atlassian Marketplace in the side navigator).
  3. Select Create new credentials.
  4. Provide the following details:

FieldDescription
App nameAny 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)
Example: https://bitbucket.mycompany.com/

Logo URL

A URL to the Bitbucket logo, which will be used as an icon in the list of credentials: BASE_URL/plugins/servlet/create-branch/icon.png
Examplehttps://bitbucket.mycompany.com/plugins/servlet/
create-branch/icon.png

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.
Examplehttps://bitbucket.mycompany.com/plugins/servlet/
create-branch?issueKey={issue.key}&issueSummary={issue.summary}

      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:

  1. In the Bitbucket Data Center Administration area, select Jira Cloud Integration (under System).
  2. Select Register site.
  3. Complete the form using the OAuth credentials you created in Jira Software Cloud by providing the following details:

register jira in bitbucket form

FieldDescription
Site nameAny 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.
Examplemycompany.atlassian.net
Site URLThe site URL of your Jira Software Cloud site.
Examplehttps://mycompany.atlassian.net/
Client IDCopied from Jira Software Cloud OAuth credentials page.
SecretCopied from Jira Software Cloud OAuth credentials page.

       4. Select Submit.

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.

Last modified on Sep 30, 2021

Was this helpful?

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