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.
- Choose Manage account.
- (Optional) If connecting a team, choose the team from the Account dropdown.
- Click OAuth under 'Access Management'.
- Click Add consumer.
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)
- 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.
- Click Save.
- 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:
- Choose Edit Your Profile.
- Select Applications.
- Choose Register new application.
JIRA DVCSfor the Application Name.
Enter the JIRA URL for both the URL and Callback URL fields. Press Register Application.
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:
- Log in to JIRA as a user with administrative rights.
- From the JIRA dashboard click the (settings) icon.
- Choose Add-ons.
If the Marketplace banner appears, skip through by choosing Manage add-ons.
- Locate the 'Source Control' section and choose DVCS accounts.
The 'DVCS Accounts' page is displayed.
- Click Link a Bitbucket or GitHub account.
The 'Add New Account' page is displayed.
- Choose a Host value.
Enter a Team or User Account name.
For example, if you want to link the account that owns the
https://bitbucket.org/tutorials/markdowndemorepository then you would enter
tutorialsfor the Team or User Account value. Linking the
tutorialsaccount links all of that account's repositories, not only the
- 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.
- Leave the default auto link and smart commits (recommended) as is or change them.
- Grant access when prompted:
- 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.
Automatic synchronisation and temporarily disabling a link
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
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.
Was this helpful?
Thanks for your feedback!