Getting started with Bitbucket and JIRA Cloud

Learn how you can connect the Bitbucket code hosting service with JIRA Cloud.  Connecting Bitbucket to JIRA gives your team the power to see commits, branches, pull requests. You can also create branches and see the status of pull requests all from the  development panel in JIRA or JIRA Agile.

You won't see the builds reference shown in the screenshot above unless you Integrate JIRA with Bamboo.

On this page:

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:

About what you are supplying

Up to 30 character username. You can use letters, numbers, and underscores in your username. Your username must be unique across the entire Bitbucket site.

Bitbucket appends this username to the URL for all the repositories you create. For example, the username atlassian_tutorial has a corresponding Bitbucket URL of

Email address An email address that is unique across the entire Bitbucket site. The system sends you a confirmation email.
Password A combination of up to 128 characters. If you are using a Google account to sign up the system uses that password. You are responsible for ensuring that your account password is sufficiently complex to meet your personal security standards.

To sign up for a Bitbucket account:

  1. Open 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.

Teams are comprised of       Which are

Who develops the code and manages the team.

Each user has an individual Bitbucket account which can be added to (or removed from) any group or team within the Bitbucket universe.


What users can do and where they can go.

Groups provide permissions (administrator, read/write, read only) to groups of individual users, and are assigned to repositories for the team.


Where the code lives.

The repository is where you store, access, create, develop, modify, and share the code for a project

Create a team

The following process and infographic describe 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.


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.
    Note: you are already a member of the team and the administrator by default.
  4. Click 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.

 When editing a team, log into an account with administrative access to the team. To add a user to a team, you add the user to one of that team's groups by doing the following:

  1. Log in to Bitbucket as a user with administrative rights on the team.
  2. Select the team you want to administer from the Teams list.
    The system takes you to the team profile page. 
  3. Click Manage team.

    The system takes you to the Groups page in the team's account settings.
  4. Locate the group you want to add the user to.
  5. Enter a Username or email address in the field provided.

    When you type in the field, the system attempts to auto complete the name for you. You can also enter a email address. 
  6. Click Add.
    If you entered an email address and it has a corresponding Bitbucket account, the system resolves the account for you. If Bitbucket could not resolve the address, it sends the user an invitation to join the team by creating a Bitbucket account. 
  7. Repeat steps 5-6 for each user you want to add.

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

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

Whether you have no files or many files, you'll first want to create a repository on Bitbucket Cloud. From there, you can clone your repository to your local system and start working on it.

To create a repository, do the following:

  1. Log into Bitbucket Cloud under your individual account.
  2. Click Repositories > Create repository or the Create new repository link.
  3. Choose a repository Owner
    This only appears if you are creating under an account with membership in one or more teams. 
  4. Enter a Name and Description for your repository.
  5. Tick Private if you want to hide your repository from the general public, so that only selected people can see it.
  6. Select the Repository type.
  7. Click Create repository.

If you create a repository with mixed upper and lower case name, Bitbucket converts the name to all lower case in the repository URL. The name appears in mixed case in the UI. You cannot create two repositories with names that result in the same URL.

After you create a repository, Bitbucket provides you with a help panel. This help panel is an easy way to get command tips for moving forward.

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

Tips, Tricks, and Links to More Information

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:

key A string generated by the Bitbucket system.
secret A string generated by the Bitbucket system.
authorizing account The account that authorizes the token.

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 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.

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 DVCS 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:

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport