Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

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

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.

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.  

Bitbucket

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. Click OAuth in the Access management section.
  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.

    make sure you enter the JIRA BASE URL (https://example.atlassian.net) NOT the dashboard URL (https://example.atlassian.net/secure/Dashboard.jspa for BOTH the Homepage URL and Authorization callback URL fields. see: DCON-467 - Entering mismatched URL for GIT causes error Closed

    JIRA 6.2 the url is https://example.atlassian.net/plugins/servlet/oauth/authorize

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 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 the Add button. 

    Associating Github account and Redirected to a blank Page here see: DVCS connection to Github produces blank page

  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 OAuth in the Access management section 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.

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

22 Comments


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

  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

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

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

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

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

    Ian

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

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

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

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

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


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

       

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

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


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

    1. 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. It seems that DVCS Connector ignoring http proxy parameters!

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

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

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