Connect Bitbucket Cloud to Jira Data Center

When your Bitbucket Cloud workspace is connected with Jira Data Center, the members of that workspace sees their branches, commit messages and pull requests right in the context of the Jira issues they're working on. Read more in Integrating with development tools.

Connect a Bitbucket Cloud account with Jira Data Center

To connect your Bitbucket Cloud account with Jira Data Center, you use the DVCS Connector provided in Jira.

You'll need to have admin permissions on both Jira Data Center and on the Bitbucket Cloud account you want to connect. 

There are just a couple of steps:

Step 1. Create an OAuth access token for your Bitbucket Cloud account

The DVCS Connector requires an OAuth access token, which you create in your Bitbucket Cloud account. You should create the access token in the Bitbucket Cloud account that owns the repositories you want to link. If you are linking repositories for a workspace, you should generate this token using the workspace account. 

Create the OAuth token as follows:

1. From Your profile avatar, select a workspace. 

2. Select the Settings cog on the top navigation bar.

3. Select Workspace settings on the Settings dropdown menu.

4. Under Apps and features on the left sidebar, select oAuth Consumers. 

5. Add consumer.

6. Enter the following details:
   Name: Enter 'JIRA DVCS' for this example.
   Description: Enter a helpful reminder of the purpose of this token.
   Callback URL: A callback URL is required if you are using OAuth 2. Also, if you’ve enabled This is a private consumer, you must provide a callback URL.

7. Select the following permissions: 

   • Account: Write

   • Repositories: Admin (but not Repository: Write)

   • Pull requests: Read

   • Webhooks: Read and write These are the minimum permissions required by the Jira DVCS connector.
     Selecting additional permissions will have no adverse affects on the integration.

8. Click Save.

9. Click the name of your new consumer to see the OAuth Key and Secret values.

10. Keep your browser open to your DVCS and go to the next step.

Step 2. Add the OAuth token in Jira Data Center

After you create a key and secret in Bitbucket Cloud, you go to Jira Data Center and enter the account, the OAuth key, and secret as follows:

1. Log in to Jira Data Center as a user with admin permissions.

2. From the Jira Data Center dashboard click the (settings) icon.

3. Choose Applications.

4. Choose DVCS accounts from the 'Integrations' section on the left.

5. Click Link Bitbucket Cloud or GitHub account.

6. Choose 'Bitbucket Cloud' as the Host value.

7. Enter a Workspace or User Account name.

8. Copy the OAuth Key and Secret values from your Bitbucket Cloud account into the dialog.

9. Uncheck or disable the auto link and Smart Commits defaults, if necessary.

10. Click Add.

11. Click Grant access.
    
    

The account you just connected and all of its repositories appears in the 'DVCS accounts' page in Jira. The initial synchronization starts automatically.

DVCS Connection notes

The DVCS Connector does not automatically trust the key and secret. It asks you to authorize the connection using an account and password combination. The authorizing account need not be the account you used to create the key and secret, but it should have administrative access on all the repositories you want to link. 

When you link an account using the DVCS Connector, the connector adds a post-commit web hook to all the repositories owned by the account in Bitbucket Cloud. When a commit happens, the web hook passes commit information to the DVCS Connector for processing.

On the Jira side, the repositories owned by your Bitbucket Cloud account appear on the 'DVCS accounts' page. A member of the workspace may create repositories under their individual Bitbucket Cloud account, but assign the workspace as the owner. These repositories also appear in the list.

Automatic synchronization and temporarily disabling a link

After you link an account, Jira automatically starts looking for commits that reference issue keys. The summary shows the synchronization results and errors, if any. A synchronization of commit data from the Bitbucket repository to Jira can take some time. As the synchronization progresses, the commits appear in related issues. You can always enable and disable the linking of repositories with Jira Software as needed. 

Example of how commit information appears in a Jira project

When a developer makes a commit, they should add a Jira issue key to the commit message, like this:

Jira uses the issue key to associate the commit with an issue, so the commit can be summarized in the Development panel for the Jira issue. Read more in Integrating with development tools.