Linking Bitbucket and GitHub accounts to JIRA

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

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:

key A string generated by the DVCS system.
secret A string generated by the DVCS system.
authorizing account The 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 service to the repository on the DVCS system. The post-commit service 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 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.

Link a DVCS account to JIRA

When you link a Bitbucket or GitHub account to JIRA, you create an OAuth access token in the DVCS tool and then add that token to JIRA.

You'll need to 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 create the OAuth access token on your DVCS account. If you are linking repositories for a team, you should generate this token using the team account. 

Generate the new OAuth token in either Bitbucket, GitHub, or GitHub Enterprise, depending on which DVCS hosts your repositories. 

Generate a new token in Bitbucket

Log in 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. Click OAuth under 'Access Management'.
  4. Click Add consumer.
  5. 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 instance (for example, https://example.atlassian.net)
  6. 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.
  7. Click Save.
  8. Keep your browser open to your DVCS and go to the next step.

Generate a new token in GitHub or GitHub Enterprise

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

    Make sure you enter the JIRA Base URL (for example, https://example.atlassian.net) for both the Homepage URL and Authorization callback URL fields. Don't use the dashboard URL (https://example.atlassian.net/secure/Dashboard.jspa). 

    See DCON-467 - Entering mismatched URL for GIT causes error Closed

    For JIRA 6.2, the URL to use is https://example.atlassian.net/plugins/servlet/oauth/authorize.

  6. Keep your browser open to your DVCS and go to 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 Manage add-ons.
  4. Locate the 'Source Control' section and choose DVCS accounts.
    The 'DVCS Accounts' page is displayed.
  5. Click Link a Bitbucket or GitHub account.
    The 'Add New Account' page is displayed. 
  6. Choose a Host value.
  7. Enter a Team or User Account name.

    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.

  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 Add

    If you are associating a GitHub account and get redirected to a blank page, see: DVCS connection to GitHub produces blank page

  11. Grant access when prompted:



  12. Upon success, the 'Managed DVCS Accounts' page is displayed with your account. 

The account you just connected and all of its repositories appears in the 'Managed 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 OAuth in the 'Access Management' section and you'll see a listing similar to the following:


     
  • The DVCS Connector programmatically adds a post-commit service to each of the account's repositories. To view this service, choose  Settings, then click Services. 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

Was this helpful?

Thanks for your feedback!

30 Archived comments

  1. User avatar

    Mike Timmons


    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.

    31 Oct 2013
    1. User avatar

      Boris Berenberg [Atlassian]

      Hey Mike,

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

      Cheers,
      Boris 

      31 Oct 2013
  2. User avatar

    Mauricio Leyzaola

    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!

    20 Nov 2013
    1. User avatar

      Satin

      I agree, the way git handles the changes is the best way ever, it provides a better insights about the what and when changes were made in a more detailed manner. Documentation about linking your repo with JIRA is also pretty clear. 

      16 Jul 2015
  3. User avatar

    Marcin Dulak

    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

    05 Mar 2014
  4. User avatar

    Ross Westerbur

    Should I expect this to result in a link being made in the Bitbucket application navigator? I've completed the process described on this page, but I only see the "Connect Bitbucket with other great Atlassian products..." message. I've been able to link successfully from the Bitbucket application navigator to JIRA previously, but that was for an OnDemand instance. It does not seem to work for my Download instance. Or is it just not possible to configure the Bitbucket application navigator to point to a non-OnDemand JIRA?

    Edit: answered at https://answers.atlassian.com/questions/221557/how-do-i-get-bitbucket-to-link-to-jira-via-the-shortcut - as of this comment, Bitbucket's application navigator can only point to an OnDemand JIRA instance.

    04 Jun 2014
  5. User avatar

    Mauricio Leyzaola

    Setting up my Bitbucket and Github account was a breeze. There is a small delay (like 30 secs.) between commits and the issue, but I think it is really of no importance. Thanks a lot!

    16 Jun 2014
    1. User avatar

      Zehua Liu [Atlassian]

      A small delay is expected, as the DVCS Connector in JIRA relies on hooks from Bitbucket or GitHub to inform JIRA that there's a change (e.g., a new commit or a update to a pull request) and then it goes to Bitbucket or GitHub to fetch the updated info.

      If hooks are not configured or JIRA is not reachable from Bitbucket/GitHub, then the delay might be up to one hour, as there is still an hourly synchronization of commits/branches/pullrequests happening regardless of the hooks configuration.

      19 Aug 2014
  6. User avatar

    Ian Wells

    this step by step was especially helpful setting up our new JIRA with existing bit bucket. Looking good!

    Ian

    18 Aug 2014
  7. User avatar

    Jonas Mosbech

    Great stuff. 

    I've got just one question: Is it possible to access the commit information registered on a ticket through the API? It doesn't seem like the information is included in the regular REST issue endpoint (/rest/api/2/issue/:issue_no).

    Thanks

    10 Nov 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hi Jonas,

      The REST issue endpoint you mention only applies to issues in the native Bitbucket issue tracker. I'm not currently able to find a JIRA API doc but confess I didn't dig too long.

      Currently you cannot get this using the Bitbucket API, you can, of course, get the commit information itself but not what is reflected in the issue in JIRA. You might find this in the JIRA API doc.

      Sorry I was not more helpful. (sad)

      Happy coding,

      Dan

      10 Nov 2014
      1. User avatar

        Jonas Mosbech

        Thanks for a quick reply. And sorry that I wasn't being more clear: the API endpoint I'm referring to is actually in the JIRA API. I somehow missed that this was the Bitbucket wiki and not the JIRA one. However, I did some more digging and it turns out that this info is not currently available through the API, but I'm not the only one interested in it:

        JRA-35331 - Create API resource that expose DVCS commits data. Open

        10 Nov 2014
  8. User avatar

    Ryan Flores

    Are there any plans to address this issue?

    JRA-38738 - Ability to link a JIRA project to a specific Bitbucket (or Github) repository Open

    Once our company grows and we start segmenting into different teams, I want JIRA teams/groups to only have access to specific projects in Bitbucket, which will more than likely also be segmented into their corresponding teams.  If there's a workaround to dealing with this, we would definitely like to know. Thanks!

    19 Dec 2014
  9. User avatar

    Jan Dockx

    When trying to link to a GitHub Enterprise account, I am asked "Please be sure that you are logged in to GitHub Enterprise before clicking "Continue" button." When I click "Continue", I get

     

    Oh, it seems that we've lost a page.
    Maybe you should raise an issue?

    Please notify your System Administrator if this problem caused you data loss

    Please look for misspellings in the address:
    https://HOSTNAME/jira/login/oauth/authorize

    or just:

     

    Does anybody know what I am doing wrong? What does being "logged in to GitHub Enterprise" mean? I am logged in with a GitHub account that is an Owner of a Github Enterprise account, and I use a "Application" definition created under the Enterprise account. That doesn't seem to work.

     

    (When I instead try linking to a GitHub account (not GitHub enterprise), I do get an authorization page, but then "Invalid credentials, please reset OAuth settings".)

    I also note that, in the "Add New Account" dialog, when selecting GitHub Enterprise, there is a mandatory "Host URL" field. In the above documentation, it just says, 

    1. Choose a Host value.

     

    I am beginning to think that this should not be the JIRA host URL, but I can't find any other explanation. Also, https://help.github.com/articles/integrating-jira-with-your-projects/ doesn't mention it. I did find out that this is where my browser is redirected: <Host URL>/loging/oauth/authorize. But shouldn't that be the regular GitHub URL?


    23 Dec 2014
    1. User avatar

      Boris Berenberg [Atlassian]

      The Host value should be the URL of your Github Enterprise instance.

       

      23 Dec 2014
      1. User avatar

        Jan Dockx

        Thx for the quick response, Boris.

        ... which leads me to the conclusion that we don't have a GitHub Enterprise account (smile) ...

        GitHub Enterprise is the on-premises version of GitHub.com.

        Terms and definitions, definitions (smile)

        We have a GitHub Organization account.

        Next try ...

        23 Dec 2014
  10. User avatar

    Jan Dockx

    When trying to link to a GitHub Organization account, following the above documentation, and https://help.github.com/articles/integrating-jira-with-your-projects/ (they both say exactly the same), I get to the stage where I am asked to authorize access. When I do, I am returned to JIRA, I get a dialog that says 

    Error!

    Failed adding the account: [Invalid credentials]

    After clicking further, I do see the "link", but it is annotated:

    Invalid credentials, please reset OAuth settings

    In GitHub, however, for the "Application", I now see

    1 user

    where before, there were 0 users.

    While doing this, I am logged in with a GitHub account, that is an owner of the organization account, and as a JIRA Administrator.

    Any ideas?


    23 Dec 2014
  11. User avatar

    oliversecluna

    Hi,

    Does the Bitbucket user need to have admin access to the repository that is being linked? I am working with a client who would like to connect a Bitbucket repository owned by me, to a JIRA account owned by them. The client has read / write access but not admin access to the Bitbucket repository.

    Thanks

    12 Feb 2015
    1. User avatar

      Ryan Flores

      No, the user doesn't need admin access. All your client needs to do is follow the instructions above. As long as you give that person access to your repository, your client will be able to do things like create branches, commit code, etc.

      12 Feb 2015
  12. User avatar

    Dorde Torbica

    It seems that DVCS Connector ignoring http proxy parameters!

    13 Feb 2015
  13. User avatar

    Patrick Mitchell

    This page gives incorrect information as to what the GitHub Authorization Callback URL should be:

    Enter the JIRA URL for both the URL and Callback URLfields. Press Register Application.

     

    The correct authorization callback URL should be

    JIRA_BASE_URL + “/plugins/servlet/oauth/authorize”

    as per http://blogs.atlassian.com/2014/04/connecting-jira-6-2-github/

    17 Mar 2015
  14. User avatar

    Sebastian Slutzky

    I've got this working between github.com and JIRA cloud. I now need to link a repository locally hosted on github enterprise with JIRA cloud. Our local github only accessible within a VPN, not publicly. How can I get both systems integrated?

    26 Mar 2015
  15. User avatar

    Ron Rudy

    Is there a way to sync Bitbucket users to JIRA? Not JIRA -> Bitbucket, but the other way.

    I started with Bitbucket, so I have a team + users there, and I have recently added JIRA on to track bugs. The repository activity is syncing nicely, but I cannot seem to figure out how to have my Bitbucket users get access to JIRA? 

    Their logins aren't working; I've done the "Configure Automatic Access" step but that seems more about giving JIRA users access to Bitbucket repos.

    I need to go the other way. I don't want to have my team have to create accounts in JIRA that have to be managed separately from Bitbucket. 

    23 Apr 2015
  16. User avatar

    Reece Hart

    The instructions are missing guidance about which Permissions (https://bitbucket.org/account/user/.../oauth-consumers/new) are required for JIRA integration.

    Moreover, this is an extremely confusing, laborious process. Here's what I'd expect for users with an existing Bitbucket repo: 1) create JIRA account, 2) navigate to page to connect with Bitbucket (for good examples, see drone.io or codeship); 3) Have a menu of existing bb repos w/checkboxes to select those to bring into JIRA (including importing existing issues).

    12 Jun 2015
  17. User avatar

    Mike Borthwick

    I just wanted to add that under "Step 2. Link the account on JIRA" - section #4 could be made clearer by specifying that you need to look in the menu on the left of the page, not "search" using the search box at the top of the page. That was a another time sink right there.

    30 Jun 2015
  18. User avatar

    Quoc Vu

    I am trying to automate this procedure and would like to know if there is an API to replace the steps that we need to do on JIRA side.

    Thanks much

    13 Jul 2015
  19. User avatar

    Dave Hauver

    There's a mismatch between the instructions and the screenshot for Step 1 (Create an OAuth access) token, section 7 (select the following for permission) for Bitbucket.

    The instructions state to select:

    • Account: Write
    • Repositories: Admin (but not Repository: Write)
    • Pull requests: Write

    But the screenshot shows Pull requests as having the Read checkbox selected, not the Write. Which is correct?

    Also, if I attempt to follow the instructions as written, checking the Write permission for Pull requests forces the Write permission to be checked for Repositories, which contradicts the specific instruction to not select it.

    17 Jul 2015
  20. User avatar

    Peter Grainger

    +1 on Dave Hauver's observation.

    I followed the screenshot configuration as it gives less access and I always think it's easier to get the instructions wrong in text when the pictures are correct.

    It works OK so far, I can view all my commits in the tickets (plus it syncs with previous commits).  I'll add an additional comment if I find any issues.

    29 Jul 2015
    1. User avatar

      Paul Watson [Atlassian]

      Dave, Peter,

      Yep, as you guessed, the screenshot was correct, the text not. It's fixed now.

      Sorry for the confusion.

      04 Aug 2015
  21. User avatar

    Maicon Wagner dos Santos

    Automating JIRA synchronization process with the bitbucket?

    14 Aug 2015
Powered by Confluence and Scroll Viewport