When your GitHub or GitHub Enterprise account is linked to Jira Software, your team gets to see their branches, commit messages, pull requests, builds and deployments 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 and raises issues from GitHub's open source repository, or contact the Atlassian team for help.

Jira Software and GitHub have created free apps in their marketplaces that allow you to view activity in your source code repository inside of your Jira tickets. Linking between these accounts gives you quick, direct access to branches, commits, pull requests, builds and deployments while viewing Jira Software tickets in planning and during standups.

To connect a GitHub account with Jira Software:

1. Install the (free) GitHub for Jira app from the Atlassian Marketplace and follow the instructions to complete the installation.

2. Select Get started.

3. Select Add an Organization.

4. Find the GitHub account you want to integrate with and select Install.

You’ll see the GitHub configuration page in Jira:

Now, you can see development information about  the branches, commits, pull requests, builds and deployments that reference Jira issues on your site. Learn more about referencing issues in your development work.

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 step 2.

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 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:
   
   
    

9. Click Add. If 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 appear on the 'Managed DVCS Accounts' page. The initial synchronization starts automatically. After that, the system continues to sync your repository automatically on a regular basis.

Reset the OAuth access token for your GitHub Enterprise account

Regenerate the OAuth token as follows:

1. Log in to GitHub Enterprise as a user with admin permissions on the account.
2. Navigate to Settings > Developer settings > OAuth apps.
3. Select your OAuth app.
4. On your app page, click Revoke all user tokens to remove all old user tokens for this application.
5. Click Generate a new client secret.
6. Copy the new client secret and then delete the old client secret.
7. Go to the DVCS accounts page in Jira.
8. Click the More options (•••) menu next to your existing GitHub Enterprise account or workspace.
9. Select Reset OAuth settings.
10. Paste the existing Client ID as Key and the new client secret as Secret to regenerate the access token.

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

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

Use repo activity to automatically update issues in company-managed projects

In company-managed software projects, you can automate your issue’s workflows to transition issues when activity happens in your GitHub repos.

We recommend you do this using automation for Jira. To automate your workflow:

1. Navigate to your company-managed project.

2. Select Project settings > Automation.

3. Select the Library tab.

4. Under DevOps, select any of the pre-configured rules.

5. When previewing the rule’s configuration, select Turn it on to enable it.

Your project’s automation library comes with 3 pre-configured rules that transition issues along your workflow as development happens in your connected source code tool:

• When a branch is created → then move issue to in progress

• When a commit is made → then move issue to in progress

• When a pull request is merged → then move issue to done

You can use source code triggers to automate other parts of your Jira projects. Learn more about automation for Jira.