When your GitHub or GitHub Enterprise 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

You can integrate Jira Cloud with GitHub using the Marketplace app. If you're a long-time Jira user, you might remember this is quite different from the old method.

You can learn more about the integration from GitHub's website, or contact the GitHub team for help. 

Connect a GitHub Enterprise account to Jira Software

To connect your GitHub Enterprise 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 Enterprise account you want to link. 

There are a couple of steps:

Step 1. Create an OAuth access token for your GitHub Enterprise account

The DVCS Connector requires an OAuth access token, which you create in your GitHub Enterprise account. You should create the access token in the GitHub Enterprise 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:

  1. Log in to GitHub Enterprise as a user with admin permissions on the account.
  2. Choose Edit Your Profile
  3. Select OAuth Applications.
  4. Select the Developer Applications tab.
  5. Choose Register new OAuth application
  6. Enter a name for Application Name
  7. 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, https://myjiracloud.atlassian.net/) for both the Homepage URL and Authorization callback URL fields. Don't use the dashboard URL, such as https://myjiracloud.atlassian.net/secure/Dashboard.jspa

  8. Keep your browser open in your GitHub Enterprise 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 Enterprise, you go back to Jira Software and enter the account, the OAuth key, and secret as follows:

  1. Log in to Jira Software as a user with admin permissions.
  2. Choose > Products..
  3. From the Integrations section on the left, choose DVCS accounts.
  4. Click Link GitHub Enterprise account.
  5. Enter a your GitHub User Account name.

  6. Enter your GitHub Enterprise site URL as the Host URL.
  7. Copy the Client ID and Client Secret values from your GitHub Enterprise site into the dialog.

  8. Leave the default auto link and Smart Commits (recommended) as is or change them:

    Image showing the GitHub Enterprise link screen
  9. Click AddIf you get redirected to a blank page at this point, see DVCS connection to GitHub produces blank page.

  10. Grant access when prompted.
  11. 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.

Connection notes

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 Enterprise. When a commit happens, the DVCS Connector collects the commit message for processing.

On the Jira Software side, the repositories owned by your GitHub Enterprise account appear on the 'DVCS accounts' page. A team member may create repositories under their individual GitHub Enterprise account, but assign the team as the owner. These repositories also appear in the list.

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