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 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 link a Bitbucket, Github, 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.
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.
JIRA DVCSfor the Name.
- Leave the URL fields empty.
- Select the following permissions:
- Account: Write
- Repositories: Admin (but not Repository: Write)
- Pull requests: Write
These are the minimum permissions required by the JIRA DVCS connector. Selecting additional permissions will have no adverse affects on the integration.
- Click Save.
GitHub and 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.
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.
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:
- 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 the Manage add-ons link.
- Locate the Source Control section and choose DVCS Accounts.
The Manage DVCS Accounts page displays.
- Click Link a Bitbucket or GitHub account.
The Add New Account page displays.
- Choose a Host value.
Enter a Team or 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.
Associating Github account and Redirected to a blank Page here see: DVCS connection to Github produces blank page
- Grant access when prompted by the system:
- 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.
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
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. Settings, then click Services to display the Services page. You'll see a listing similar to the following:
Example of how commit information appears in a JIRA project
Project permissions required
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.