Connect Bitbucket Cloud to Jira Server applications
When your Bitbucket Cloud account is connected with Jira Software Server, your team sees their branches, commit messages and pull requests right in the context of the Jira Software issues they're working on. Read more in Integrating with development tools.
On this page:
Connect a Bitbucket Cloud account with Jira Software Server
To connect your Bitbucket Cloud account with Jira Software Server, you use the DVCS Connector provided in Jira.
You'll need to have admin permissions on both Jira Software Server 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 team, you should generate this token using the team account.
Create the OAuth token as follows:
- From your avatar in the bottom left, click Bitbucket settings.
If connecting a team, select your team or click View all teams for a full list, then click Settings.
- Click OAuth under Access Management.
- Click Add consumer.
Enter the following details:
Name: Enter '
JIRA DVCS' for this example.
Description: Enter a helpful reminder of the purpose of this token.
URL: Enter the URL for the Jira Software instance (for example, https://example.atlassian.net)
- Select the following permissions:
- Account: Write
- Repositories: Admin (but not Repository: Write)
- Pull requests: Read
These are the minimum permissions required by the Jira DVCS connector.
Selecting additional permissions will have no adverse affects on the integration.
- Click Save.
- Click the name of your new consumer to see the OAuth Key and Secret values.
- Keep your browser open to your DVCS and go to the next step.
Step 2. Add the OAuth token in Jira Software Server
After you create a key and secret in Bitbucket Cloud, you go to Jira Software Server and enter the account, the OAuth key, and secret as follows:
- Log in to Jira Software Server as a user with admin permissions.
- Choose Applications from the cog (settings) icon.
- Choose DVCS accounts from the 'Integrations' section on the left.
- Click Link Bitbucket Cloud or GitHub account.
- Choose 'Bitbucket Cloud' as the Host value.
Enter a Team or User Account name.
Copy the OAuth Key and Secret values from your Bitbucket Cloud account into the dialog.
- Change the auto link and Smart Commits defaults if necessary:
- Grant access when prompted:
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 Software side, the repositories owned by your Bitbucket Cloud account appear on the 'DVCS accounts' page. A team member may create repositories under their individual Bitbucket Cloud account, but assign the team as the owner. These repositories also appear in the list.
Automatic synchronization and temporarily disabling a link
After you link an account, Jira Software 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 Software 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 Software project
When a developer makes a commit, they should add a Jira Software issue key to the commit message, like this:
git commit -m "PROJ-123 add a README file to the project." git push origin <branchname>
Jira Software uses the issue key to associate the commit with an issue, so the commit can be summarized in the Development panel for the Jira Software issue. Read more in Integrating with development tools.
Project permissions required