Connect Jira Cloud to GitHub
When your GitHub account is linked to Jira Software, your team gets to see their branches, commit messages and pull requests right in the context of the Jira Software issues they're working on. Read more in Integrating with development tools.
Connect a GitHub account to Jira Software
To connect your GitHub account to Jira Software, you use the DVCS Connector provided in Jira.
By the way, you'll need to have admin permissions on both Jira Software and on the GitHub account you want to link.
There are a couple of steps:
Step 1. Create an OAuth access token for your GitHub account
The DVCS Connector requires an OAuth access token, which you create in your GitHub account. You should create the access token in the GitHub account that owns the repositories you want to link. If you are linking repositories for a team, you should generate this token using the team account.
Create the OAuth token as follows:
- Log in to GitHub as a user with admin permissions on the account.
- Choose Edit Your Profile.
- Select OAuth Applications.
- Select the Developer Applications tab.
- Choose Register new OAuth application.
- Enter a name for Application Name.
Enter the Jira Software URL for both the URL and Callback URL fields. Use lower case. Press Register Application.
Make sure you enter the Jira Software Base URL (for example,) for both the Homepage URL and Authorization callback URL fields. Don't use the dashboard URL, such as
- Keep your browser open at your GitHub account while you go on with the next step.
Step 2. Add the OAuth token in Jira Software
After you create a key and secret in GitHub, you go back to Jira Software and enter the account, the OAuth key, and secret as follows:
- Log in to Jira Software as a user with admin permissions.
- From the Jira Software dashboard click the cog (settings) icon.
- Choose Applications.
- From the Integrations section on the left, choose DVCS accounts.
- Click Link Bitbucket Cloud or GitHub account.
- Choose 'GitHub' as the Host value.
Enter a Team or User Account name.
Copy the Client ID and Client Secret values from your GitHub site into the dialog.
- Leave the default auto link and Smart Commits (recommended) as is or change them:
Click Add. If you get redirected to a blank page at this point, see DVCS connection to GitHub produces blank page.
- Grant access when prompted:
- When Jira connects successfully, you'll see your account on the 'DVCS accounts' page.
The account you just connected and all of its repositories appears in the 'Managed DVCS Accounts' page. The initial synchronization starts automatically. After that, the system continues to sync your repository automatically on a regular basis.
The connector does not automatically trust the key and secret. It asks you to authorize the DVCS connection using an account and password combination. The authorizing account need not be the account you used to create the key and secret, but it should have administrative access on all the repositories you want to link.
When you link an account using the Jira DVCS Connector, the connector adds a post-commit web hook to all the repositories owned by the account in GitHub. When a commit happens, the DVCS Connector collects the commit message for processing.
On the Jira Software side, the repositories owned by your GitHub account appear on the 'DVCS accounts' page. A team member may create repositories under their individual GitHub account, but assign the team as the owner. These repositories also appear in the list.
Automatic synchronization and temporarily disabling a link
After you link an account, Jira Software automatically starts looking for commits that reference issue keys. The summary shows the synchronization results and errors, if any. A synchronization of commit data from the GitHub repository to Jira Software can take some time. As the synchronization progresses, the commits appear in related issues. You can always enable and disable the linking of repositories with Jira Software as needed.
Example of how commit information appears in a Jira Software project
When a developer makes a commit, they should add a Jira Software issue key to the commit message, like this:
git commit -m "PROJ-123 add a README file to the project." git push origin <branchname>
Jira Software uses the issue key to associate the commit with an issue, so the commit can be summarized in the Development panel of the Jira Software issue.
See Integrating with development tools for more information.
Project users must have the 'View Development Tools' permission to see commit information in the Development panel in a Jira Software issue. A Jira Software admin can edit a project's permission schema to grant this permission. See Managing Project Permissions.