You can link your Bitbucket Cloud account and its repositories to Jira, and see the development information from pull requests displayed in your issues.

Overview

Depending on whether you are migrating your connection from OAuth 1.0 to OAuth 2.0, or want to set up the OAuth 2.0 connection from scratch, complete one of the following processes.

Setting up the OAuth 2.0 connection from scratch

1. In Bitbucket, create a private OAuth 2.0 consumer.
2. In Jira, link Bitbucket cloud using OAuth 2.0.

Migrating from OAuth 1.0 to OAuth 2.0

1. In Bitbucket, update your OAuth consumer to include a callback URL.
2. In Jira, delete the OAuth 1.0 connection.
3. In Jira, link Bitbucket cloud using OAuth 2.0.

Create or edit the OAuth private consumer in Bitbucket cloud

If you are setting up the connection from scratch, create a private OAuth 2.0 consumer in your Bitbucket cloud workspace to give Jira permissions to access Bitbucket.

If you are upgrading your connection from OAuth 1.0 to OAuth 2.0, add a callback URL to the existing consumer.

To create the OAuth access token in Bitbucket Cloud:

1. Select avatar, then All workspaces. 

2. Select the relevant workspace.
3. Select Settings, then Workspace settings.
4. From Apps and features, select OAuth consumers.

5. To create a new consumer, select Add consumer.
   To update an existing consumer, select More actions ..., then Edit next to the consumer you want to update.

6. Enter the following details: 

   • Name: A descriptive name, for example, Jira DVCS.

   • Description: A helpful reminder of the purpose of this token.
   • URL: A URL for your Jira Software instance, for example, https://example.atlassian.net.
   • Callback URL: A placeholder value. We recommend setting it to http://localhost or using your Jira instance's URL.
     

     Callback URL is required to create an OAuth 2.0-compatible consumer, but its value is not used in the authentication flow.

7. Select the This is a private consumer checkbox.

8. Select the following permissions:

   • Account: Write

   • Repositories: Admin (but not Repository: Write)

   • Pull requests: Read

   • Webhooks: Read and write
9. Select Save.
10. Select the name of your consumer to see the OAuth key and OAuth Secret values. You’ll need them when adding your Bitbucket cloud account in Jira.

Delete OAuth 1.0 connection to Bitbucket cloud

To remove an OAuth 1.0 Bitbucket cloud connection from Jira:

1. Go to Administration, then Applications.
2. In the sidebar, select DVCS accounts.
3. In the list, find the connection you want to remove. Select More actions ...,  then Delete account and confirm.

After the account is removed, you can move on to creating the new OAuth 2.0 connection.

Link your Bitbucket cloud account

To add a Bitbucket cloud account in Jira:

1. Go to Administration, then Applications

2. In the sidebar, select DVCS accounts.

3. Select Link an account.

4. In Host, select Bitbucket cloud OAuth 2.0.  

5. Copy Key and Secret values from Bitbucket cloud, and enter them as Client ID and Client Secret in Jira.

6. Leave the default values for Auto Link New Repositories and Enable Smart Commits
    (recommended), or change them if required.
7. Select Add. 
   
   

What’s next?

Here’s what happens after adding your account:

• Syncing repositories: Your account appears on the DVCS page and Jira starts syncing its repositories, if you decided to link them automatically. For details, see Integrating dev tools using DVCS.

• Matching issues: If your commits and pull requests include issue keys, Jira will try to find them and add the relevant information to your issues. For details, see Referencing issues in your development work.

• Displaying dev info: If referenced correctly, the dev information will be added to your issues to give everyone involved more context. For details, see Viewing the dev info for an issue.

• Workflow triggers: One of the benefits of integrating your development tools is adding workflow triggers that, for example, lets you change the issue status after you create a new branch. For details, see Configuring workflow triggers.