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

Important Tips for Bitbucket Users

If you added Bitbucket to your Cloud 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. 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  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

  • No labels


  1. I can see this information has been recently edited. Hope there is more editing to come as there is a missing image after the text "The connector programmatically adds a service to the repository's service listing. To view this listing, choose the Admin tab on your Bitbucket repository and display the Services page. You'll see a listing similar to the following:"

    I am struggling to work out how the JIRA project is linked to the Bitbucket repository so any work on this page is appreciated. Thanks!

    1. Thank you for the catch Ben.  This is fixed.  By setting up the OAuth connection, you allow the DVCS Connector to create POST commit hook service on each of your repositories.   A POST commit hook is little piece of code that happens each time a commit is made on the repo.  I've tweaked the text to make this relationship clearer.

      1. Can the connector also show details of pull requests? Or only commits?

        1. Just the commits at the moment.  

  2. This page requires update, especially the screenshots.

    1. Thanks for the comment. We are about to come out with a new release.

  3. For github, does the post-commit hook run on all branches, or just on master?


    The reason I ask is that this would be a requirement of using a workflow similar to git-flow, or github pull-requests.  This is especially important if the master branch is considered the stable branch, while other feature branches are not stable, could be amended, commits added, etc...   The concern is that some process is to be maintained as to when the JIRA tasks are actually considered closed.


    For example:  someone commits to new feature branch 'my-bug-fix' with a smart commit message to close a JIRA issue.  Later on, after a code review it's determined that there is still a bug.  The last commit on 'my-bug-fix' branch is amended, or another commit is added that actually fixes the bug.  

    Will the first commit that didn't fix the issue cause the related JIRA task to be closed, or does the DVCS connector only add the hook to the master branch, so when the feature branch is merged, then the post-commit hook is triggered?

  4. Hello,

    I am new to JIRA.

    I have followed the exact steps above to connect my Github account.

    I have the Organisation account and the personal one.

    I wish to use the Org. account.

    I create the Application based on the instructions and now I can see the list of repos I have.

    It might be stupid, but my question is this

    "how to link a project to a certain repo?"

    Thank you in advance.


    1. Jad,

      Linking the account links all the repos.  On the GitHub side, when a user commits code they just need to reference a JIRA project issue, for example a commit message like this:

      Fixed issue PROJ-23 by resolving NPE from foobar()

      Then, the commit will show up in JIRA under the Commits tab for the PROJ-23 issue.  If a user mentions issues from multiple projects in a single commit, the commit shows up in both projects.  

      Fixed issue PROJ-55 and OTHER-45 by resolving confusing dialog.

      This shows up in both the PROJ project and the OTHER project issues in JIRA.


  5. Please, Atlassian, add an issue importer for those of us who'd like to move issues out of Github and into JIRA OnDemand!

  6. It isn't clear from this document which URIs you need to supply when setting up github (for example) as my initial attempt using:

    didn't work. The correct form is simply to use just the domain name (for OnDemand instances), thus:

    It would also be helpful to update the documentation so that it OAuth key/secret generated by GitHub are referred to as Client ID/Secret as this isn't immediately obvious, but is described clearly by third parties.

  7. I do not see View Version Control listed as a permission to add to the JIRA 'Default Permission Scheme'? How do I do this?

    In BitBucket I created the OAuth credentials as above. In JIRA I have set up the DVCS Accounts to link it to my BitBucket account and see the list of repositories in JIRA now.

    Above it says:

    Project users must all have View Version Control permissions. Without the proper permissions, users cannot see the Activity tab


    But in JIRA when I go into the Default Permission Scheme from the 'Settings (cog icon) > Issues > Permission Schemes' I don't see theView Version Control permissions as a permission to add?

    1. Hi Simon, this is general JIRA limitation and you found a bug in the product and doc. I'll fix this.

      Project users must all have View Development Tools permissions to see the commits activity. Without the proper permissions, users cannot see the tab.

      To set this for a user:

      1. Got to Administration
      2. Select a project.
      3. Choose Permissions.
      4. Choose Actions > Edit permissions.
      5. Locate the View Development Tools permission.
      6. Press the Add link on this permission.
        The Add New Permission page appears. 
      7. Fill out the page and press Add.
  8. I tried to link the existing bitbucket account into the JIRA OnDemand. I followed through this instruction until step 2.Link the account on JIRA. I stuck at the following step because I cannot find the "Source Control" under the "Manage add-ons" link?

     "4. locate the Source Control section and choose DVCS Accounts The Manage DVCS Accounts page displays."

    Any suggestions would be appreciated.

    1. The Source Control section appears along the left-hand side of the page.  I've tweaked the documentation to clarify this.

      1. I'm in the same boat. There's no Source Control section on the left-hand nav panel, and there's no Source Control section in the listed add-ons (even when I select "All add-ons").

        1. My bad. I was in Confluence, not Jira. Switching, then going to Add-Ons worked as advertised.

          (Atlassian, please unify the Confluence and JIRA experience.)

  9. Is there a way to programmatically report all commits on a JIRA issue, where the linkage is between JIRA OnDemand and GitHub (cloud based service) ? 

    Note, I have followed these instructions and do see the commits on the Commits tab...I just need to report them via some API



    1. Tylee, I'm not sure I understand what data you are trying to report.  JIRA has a REST API and so does GitHub. My suggestion would be that you start with those APIs – one of them should be appropriate.

      1. Sorry, let me elaborate...

        I've extensively (perhaps not enough) read thru the JIRA REST api docs and haven't found anything that will report back the individual commits associated with a particular JIRA issue. 

        I can see the commits on the Activity/Commits tab (Sorry, unable to attach image)

        This appears the same as a request made by 'Bryan Grimes' here:


        When our automation generates Release Notes, we query all the JIRA issues that were included in the build, then read all the commit info associated with each issue so we know what files were changed. 





        1. Thanks for the followup Ty.  There is a rest API that gives you access to the visible data:


          That API is returning comments on the Commits tab but not the commit data itself. I've queried the JIRA team to see if there is a way to get to this data. (I saw the Answers comment you mention.)

          1. Thank you Manthony,

            I have indeed tried that ?expand query string on all available fields, but as you mentioned, it doesn't return what I need.

            Thanks for asking the JIRA team... I look forward to a response.



            1. Tylee I've just heard back from the team.  Confirmed, JIRA has no publicly available API that exposes commit data.  I'd encourage you to visit and file an enhancement request. We have projects underway or coming up that could correct the situation.

              1. Thanks very much, Manthony

                I suspected as much, and I'll submit an ENH req!

                Much appreciated.


                1. Just for reference sake, here is the improvement request created by the OnDemand support on my behalf:

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


    Trying to connect for the first time, but I get Error obtaining access token.  Response is invalid.  Possibly bug in releases of GitHub Enterprise prior to 11.10.290.  We have 11.10.308, so this is higher level.

  11. Hello guys,

    I'm not sure if this is a stupid question, but I'm starting with JIRA and I have a concern. Is it possible to show commit messages related to a Project in JIRA but not related to a specific Issue?

    I see that the commit messages appear under the "Activity" tab in each Issue, but is it possible to see the commits from a project perspective?


    1. Carlos,

      Currently, I believe the only way to see the commits from the project perspective is from the code repository itself.  For example, each Bitbucket repository has a Commits tab that lists all the commits on that repo.


  12. Anonymous

    FYI:  With github, if you have an organization account, you can't log into it directly.  So you set up an admin user account.  When linking to JIRA DVCS, you need to specify the organization github account name (on the JIRA DVCS create link part, Step 2.5 above), not the admin user name.  You may also need to make sure that the application creation (where you create the OAuth keys) on the github side is transferred over so as to be owned by the organization account. 

  13. Anonymous

    Hello, could you please confirm what permissions github user should have for linking JIRA and github?

    Is it enough to have User account with Collaborator permissions or Organization account is required. if Organization account what particular level of access the user should have.




  14. Is there a response for James Cuzella? I think I have the same issue: I don't want issues closed b/c someone checked into their branch, only when a merge to master occurs. Also, adding a commit tag to a merge comment in github doesn't seem to do anything. Thanks. 

  15. I have an existing BitBucket account that has been converted to a "team" account and now I'm attempting to link it to my OnDemand JIRA installation. I've followed the guide to create my application entry for JIRA but JIRA refuses to connect. It complains that the team ID in question is invalid. Any thoughts would be appreciated.

    1. We are also trying to link an existing bitbucket to our JIRA OnDemand and have the same issue.

      Do we need to have a bitbucket OnDemand  to be able to connect a to JIRA OnDemand? Or a regular account also should work.

  16. I'm unable to link my bitbucket account with JIRA OnDemand. 

    I'm getting the same error:


    Invalid user/team account.

    Does anyone know how to bypass this?


    1. Unable to connect too.

      1. Unable to make the DVCS connection : same error "Invalid user/team account"

  17. Hi all,

    We are aware of some issues with the JIRA DVCS connector. We have a fix in the works and should have it deployed soon. Please watch this issue for updates: JRA-36448 - JIRA OnDemand Issues not receiving commit messages from Bitbucket Resolved


  18. I have a account in Bitbucket since 2011, but this integration is very confunsing. I just want connect my repositories issues with Jira, but I can't.

  19. Is it possible to link (or limit) specific JIRA OnDemand projects to specific BitBucket repos?  What I am trying to accomplish is this.  If I use the DVCS connector to link to multiple repos, I don't want developers (accidentally) creating branches via the Developer Tools to unrelated repos. 

    We plan to create JIRA projects for different clients, and different repos either in a single team or multiple teams, and do not want developers branching/committing to things that are unrelated.

    I know we can establish business rules to handle this; however, it doesn't prevent mistakes from happening.  Currently, the only way I can see getting around this is by signing up for a new JIRA OnDemand account per client, then linking that account to a specific team/repo in BitBucket.  Is there a better way of handling this?  Please let me know if you need me to elaborate further.  Thanks.

  20. The level of complexity that is required to set this up is just downright disappointing (which sums up our entire JIRA experience)  While were attempting to do this via Github, it appears BitBucket it no better.

    And there is a Github JIRA importing tool, but of course it's not available for On-Demand instances.  

    Final straw for Jira, were all done and will be migrating off this ASAP. 

    1. Hi Vincent,

      Sorry to hear you're not able to get JIRA to do what you need it to do. We do happily accept all feedback (good or bad) and strive to improve our products to satisfy feature requests from our users. I've created a feature request at  JRA-38738 - Ability to link a JIRA project to a specific Bitbucket (or Github) repository New  regarding the linking of Bitbucket and Github repositories. With regards to the Github JIRA importing tool, I'm not sure if you mean our Github importer (which should work in OnDemand) or something else I'm unaware of. 

      Thanks for the feedback.


  21. Is it possible to send a newly created issue from JIRA to github?