Skip to end of metadata
Go to start of metadata

Use the JIRA DVCS connector to link a Bitbucket or GitHub (hosted or enterprise) account to JIRA.  When linked to JIRA, branches, commit messages and pull requests can all reference JIRA issues. This allows JIRA to display information about your development activity in the corresponding issue. See Streamlining your development with JIRA OnDemand.

This page explains what you need to know and do to link a DVCS account to JIRA.

Make sure you understand how JIRA connects to your DVCS account

The JIRA DVCS connector links JIRA to an account on a DVCS hosting service (Bitbucket, GitHub, or GitHub Enterprise). For this reason, the connector needs permission from your DVCS account to access your account data. The connector does this through an OAuth access token.  

You create an OAuth access token on the DVCS system (Bitbucket, GitHub, or GitHub Enterprise). You should create the access token on the account that owns the repositories you want to link.  How you create the token depends on the DVCS system; the values that make up the token are:

keyA string generated by the DVCS system.
secretA string generated by the DVCS system.
authorizing accountThe account that authorizes the token.

After you create a key and secret in the DVCS, you go back to JIRA. There, you enter the account, the OAuth key, and secret data into JIRA.

The connector does not automatically trust the key and secret.  It asks you to authorize the DVCS connection via the key and secret by supplying JIRA an account and password combination.  Authorizing is the equivalent of telling the DVCS connector:

As a Bitbucket account holder, I know this service asking for a connection with a key and secret. You are free to use them to get to this account data. 

The authorizing account is not necessarily the account that created the key and secret.  The authorizing account should have administrative access on all the repositories to be linked. 

When you link an account through the JIRA DVCS connector, the connector locates all the public and private repositories owned by the account. It adds a POST commit hook service to the repository on the DVCS system.  The POST commit hook is a piece of code that sits on the repository waiting for users to commit changes.  When a commit happens, the DVCS connector collects the commit message for processing.

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

Important Tips for Bitbucket OnDemand Users

If you added Bitbucket OnDemand to your OnDemand instance, the Atlassian purchasing system automatically created a Bitbucket team account and OAuth connection for you. This account appears on the Manage DVCS Accounts page with the logo. You shouldn't need to link additional Bitbucket accounts at all. If you want to use GitHub, you must link the GitHub accounts yourself.

Procedure to link an Account

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

Step 1. Create an Oauth access token for your DVCS account

You can choose to link a BitbucketGithub, or Github Enterprise account. You create an OAuth access token on your DVCS account.   If you are linking repositories under a team, you should generate this token under the team account.  The steps generating the token varies depending on the type of DVCS you use.  


Login 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 dropdown.
  3. Select Integrated applications.
  4. Click Add consumer.
  5. Enter JIRA DVCS for the Name.
  6. Leave the other fields fields blank.
  7. Press Add consumer.

GitHub and GitHub Enterprise

Login as a user with administrative rights on the account:

  1. Choose Edit Your Profile
  2. Select Applications
  3. Choose Register new application
  4. Enter JIRA DVCS for the Application Name
  5. Enter the JIRA URL for both the URL and Callback URL fields. Press Register Application.

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

Step 2. Link the account on JIRA

Do the following to complete the link between your DVCS and JIRA:

  1. Log in to JIRA as a user with administrative rights.
  2. From the JIRA dashboard click the  (settings) icon.
  3. Choose Add-ons
    If the Marketplace banner appears, skip through by choosing the Manage add-ons link.
  4. Locate the Source Control section and choose DVCS Accounts.
    The Manage DVCS Accounts page displays.
  5. Click Link a Bitbucket or GitHub account.
    The Add New Account page displays. 
  6. Choose a Host value.
  7. Enter a Team or Account name.

    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.

  8. Copy the OAuth Key and OAuth Secret from your DVCS site into the dialog.
    GitHub's Client ID is equivalent to the OAuth key. And the Client Secret is equivalent to the OAuth Secret
  9. Leave the default auto link and smart commits (recommended) as is or change them.
  10. Click the Add button. 
  11. Grant access when prompted by the system:
  12. Upon success, the Managed DVCS Accounts page displays with your account. 

The account you just connected and all of its repositories appears in the Manage DVCS Accounts page. The initial synchronisation 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 issue keys. The summary shows the synchronisation results and errors, if any. A synchronisation of commit data from the DVCS repository to JIRA can take some time. As the synchronisation 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 the Admin tab on your Bitbucket repository and display the Services 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.

Example of how commit information appears in a JIRA project

Project permissions required

Project users must have the View Development Tools permission to see commit information in the Development panel in a JIRA issue. A JIRA admin can edit a project's permission schema to grant this permission. See Managing Project Permissions.

Commit code similar to the following: 

hg commit -m "DVCS-2 add a README file to the project."
hg push


Your commit will be summarized in the Development panel for the JIRA issue:


See Streamlining your development with JIRA for more information.

Related pages

Managing linked Bitbucket and GitHub accounts

Processing JIRA issues with commit messages


  1. This process is way too confusing. I'm chasing my tail trying to get this to work. Althoug hit was, "old school" I was happy with my SVN, Jira, and confluence set-up before SVN was sunsetted.

    Now I find myself swimming in a cesspool of jargon and system interoperation confusion, etc.

    I'm 4+ hours into trial-and-error to get a simple commit message to a  Bitbucket repo to appear as a commit in the JIRA issue I reference in the message. The commit message in bitbucket does have a valid hyperlink to the JIRA issue, but there is no history of the commit in the JIRA issue.

    Yes, I've searched on this all but it is confusing, and given my JIRA project existed BEFORE I got Bitbucket going I wonder if that is not the problem: easier to start a new project and repo than get a new repo connected to a pre-existing JIRA project.

    1. Hey Mike,

      The integration between JIRA and Bitbucket using the DVCS plugin is supported by Atlassian. Please open a support ticket ( and we can help you get this set up. You should be able to connect a new Bitbucket repo to an existing project.


  2. Once you figured it out, the documentation is clear. In my case it was more the lacking of knowledge on how Git works that the connector itself.

    SVN was cool 5 years ago, now Git is a lot better. I can even automate the deployment to my hosted sites using webhooks and some scripting.

    Thanks a lot guys!

  3. I see the following, unexpected behaviour when linking bitbucket account to JIRA (atlassian-jira-6.2-x64.bin):

        0. configure bitbucket repository WITHOUT Issue Tracker

    1. Perform Step 1. and Step 2. form the current doc page
    2. in jira: Projects -> Import External Project -> Import from Bitbucket: the configured bitbucket project is not available at "Map Projects"
    3. on bitbucket: configure Issue tracker settings -> Private issue tracker
    4. retry 2.: result the bitbucket project is available at "Map Projects" and can be imported

    Moreover, as far as i can see there is no integration between bitbucket issues and JIRA issues, so if one wants to use JIRA for tracing issues, immediately after 4. one has to go back to "No issue tracker" on bitbucket