Before you begin

1. Bitbucket and Jira Cloud are independent services: you will have both a Jira Cloud account and a Bitbucket team each with their own set of users, permissions, and access rules.

2. Bitbucket teams are not accounts: they must be managed by an administrator (or administrators) who have individual Bitbucket accounts. However, the Bitbucket team can have its own payment plan. 

3. Every member of the Bitbucket team must have their own individual Bitbucket account. When you invite new team members using their email they are also automatically invited to sign up for Bitbucket and are automatically added to your team when they complete sign up.  
   

4. You can transfer Bitbucket repository ownership to a team: this can be helpful if you want to create a team based upon existing repositories.

Step 1. Sign up for Bitbucket and create a Bitbucket team

If you don't already have Jira Cloud, set up a trial or a paid instance.

Create a Bitbucket account

If you already have an account, you can skip this section and go to the next. When you create a Bitbucket individual account you must supply the following fields:

To sign up for a Bitbucket account:

1. Open https://bitbucket.org/account/signup/ in your browser.
2. Complete the fields in the sign up form.

3. Click Sign up.

When you are done signing in, Bitbucket places you in the Dashboard of your account. Take a second to look around the user interface. Across the side of each Bitbucket page is a series of options that let you navigate around Bitbucket. On the top bar is a link for Teams. Select Teams > Create team and move to the next section.

Create a team

To better understand how teams work let’s first take a look at how they fit into the Bitbucket environment.

Create a team

The following process describes how to create a very simple team consisting of you, one member, and one repository. Feel free to follow along in your Bitbucket account, or just read through to get an idea of what goes into creating a team.

Prerequisite:

You have an individual Bitbucket account

Create a team
Two user groups, Administrator and Developer, are created by default when you create a team.

To create a team:

1. Select Teams > Create team.
2. Fill in the available fields:
   1. Team name (when adding a team to a Jira Cloud instance, consider using the same name as the Jira Cloud instance or one you can easily identify with a specific project.
   2. Team ID 

3. Add additional team members by entering their Bitbucket username or email address and clicking Add for each person you want to invite to the new team.

   You are already a member of the team and the administrator by default.

4. Select Create.

Congratulations you have a team! You are taken to the team overview page where you can create your first team repository or manage the team's settings.

Step 2. Invite team members to your team on Bitbucket

You can add team members to your linked Bitbucket team account. These may be the same users you added to Jira.  It is your choice. Users that you add to Bitbucket need not have accounts on the Jira instance.

 To add a user to a team, you add the user to one of the team's groups, as follows:

1. Log in to Bitbucket as a user with administrative rights on the team.
2. Choose Your avatar > View all teams.
3. Choose the team you want to add new members to.
4. Choose Settings > User groups.
5. Click on the group you want to add the user to.
6. Enter the user's username or email address, then click Add:
   
   If you entered an email address that corresponds to a Bitbucket account, Bitbucket resolves the account for you. If Bitbucket can't resolve the address, it sends the user an invitation to create a Bitbucket account and join the team.

Step 3. Create repositories in or move repositories to your Bitbucket account

A repository (sometimes called a repo) contains your project code. 

The Bitbucket service allows you to create an unlimited number of public repositories.  The number of private repositories is restricted by your plan.

Step 4. Connect the team account in Jira

Make sure you understand how Jira connects to your Bitbucket account

The connector needs permission from your Bitbucket account to access your account data. The connector does this through an OAuth access token.  

You create an OAuth access token from the Bitbucket account. You should create the access token on the team that owns the repositories that you want to link.  The values that make up the token are:

After you create a key and secret in Bitbucket, go back to Jira. There, you can enter the account, the OAuth key, and secret data.

Bitbucket does not automatically trust the key and secret it will ask you to authorize the Bitbucket connection.

When you link your Bitbucket account with Jira all the public and private repositories owned by the account. It adds a POST commit hook service to the repository on the Bitbucket system.  The POST commit hook is a piece of code that sits on the repository waiting for users to commit changes.

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

Procedure to link an account

It is a two step procedure to link a Bitbucket account to Jira. To work through this procedure, you must have administrative rights on both the Jira Cloud instance and on the Bitbucket account you want to link.  

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

To link a Bitbucket account you create an OAuth access token on your Bitbucket account.   If you are linking repositories under a team, you should generate this token under the team account.   

Log in to Bitbucket as a user with administrative rights on the account.

1. Choose Manage account. 
2. (Optional) If connecting a team, choose the team from the Account drop-down.
3. Select OAuth.
4. Click Add consumer.
5. Enter Jira DVCS for the Name.
6. Leave the other fields fields blank.
7. Press Add consumer.

Keep your browser open to Bitbucket  and go onto the next step.

Step 2. Link the account on Jira

To complete the link between your DVCS and Jira:

1. Log in to Jira Cloud as a user with administrative rights.
2. From the Jira dashboard click the settings icon ().
3. Choose Applications then DVCS accounts (under 'Integrations' in the left-hand panel).
4. Click Link a Bitbucket Cloud or GitHubaccount.
5. Choose Bitbucket Cloud as your Host value.

6. Enter a Team or User Account.

   For example, if you want to link the account that owns the https://bitbucket.org/tutorials/markdowndemo repository then you would enter tutorials for the Team or User Account value.  Linking the tutorials account links all of that account's repositories, not only the markdowndemo repository.

7. Copy the OAuth Key and OAuth Secret from your Bitbucket account into the dialog.
8. Leave the default auto link and smart commits (recommended) as is or change them.
   
9. Click Add. 
10. Grant access when prompted by the system:
11. Upon success, the DVCS accounts page displays with your account. 

The account you just connected and all of its repositories appear in the DVCS accounts page. The initial synchronization starts automatically.  After that, the system continues to sync your repository automatically on a regular basis.

Automatic synchronization and temporarily disabling a link

After you link an account, Jira automatically starts looking for commits that reference existing issue keys. The summary shows the synchronization results and errors, if any. A synchronization of commit data from the 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 as needed. 

How the link appears in Bitbucket

The DVCS Connector does two things:

• It adds an OAuth consumer to the linked account's list of integrated applications. To view the listing in Bitbucket, click your profile image and select Manage Account. Click Integrated applications and you'll see a listing similar to the following:
  
   
• The DVCS Connector programmatically adds a POST commit hook service to each of the account's repositories.  To view this service, choose Settings (), then click Hooks to display the Hooks page. You'll see a listing similar to the following:
  
  
  The DVCS Connector uses its link to check for new repositories on the account, then adds this service to those as well. You see the result of all this on the Services page.

What to do next

What you do after getting started depends on your team's own knowledge and needs:

• If your team is unfamiliar with code hosting using Bitbucket or brand new to DVCS, you should work through the Bitbucket 101.
• If your team is comfortable with DVCS and Bitbucket, you might want to learn to Link to a web service in Bitbucket which will give you even more interaction between Jira and Bitbucket.
• The DVCS Connector lets you update and move Jira issues through a workflow, see processing Jira issues with smart commit messages for commands and examples of how to do this.