• Products
  • Documentation
  • Resources

Integrate GitHub with Jira

If you’re a GitHub Enterprise Server customer participating in our GitHub for Jira beta trial, please follow this link to learn more about connecting your GitHub Enterprise Server account to Jira via the GitHub for Jira app.

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. Learn more about integrating with development tools.

Connect a GitHub Cloud or GitHub Enterprise Cloud account to Jira Software

You can integrate Jira Cloud with GitHub Cloud or GitHub Enterprise Cloud using the Marketplace app. 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.

You can learn more about the integration and raises issues via the open source repository on GitHub, or contact the Atlassian team for help.

To connect a GitHub Cloud Organization 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 to go to the GitHub configuration page (or go to Apps > Manage apps and select Configure integration in the GitHub menu).

  3. Select Connect GitHub organization.

  4. Find the GitHub organization you want to integrate with and select Connect, or select Install GitHub for Jira on a new organization to install the GitHub for Jira app on another GitHub organization.

  5. Back on your GitHub configuration page, select Connect GitHub organization again and click Connect next to the organization you want to connect to your Jira site.

Once your organization is successfully connected, you’ll see it on the GitHub configuration page in Jira:

GitHub configuration page in Jira, showing a connected organization

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.

If you're using IP allowlists in your GitHub org, you may experience issues using GitHub for Jira. GitHub blocks some requests to the API even if the correct IP addresses are listed in the IP allowlist. To work around this problem, you must add the IP addresses through to your IP allowlist (you must add each IP address individually, not as a CIDR range). If our servers' IP address range changes, you must add the new IP addresses to continue using GitHub for Jira. Learn more about GitHub IP allowlist configuration.

If you experience any problems with IP allowlists, please raise an issue so we can help you.

Connect a GitHub Enterprise Server account to Jira Software

These instructions are for GitHub Enterprise Server, meaning the on-premise version of GitHub where you manage the installation on your own infrastructure. If you have GitHub Cloud or GitHub Enterprise Cloud, follow the instructions above rather than using the DVCS Connector.

To connect your GitHub Enterprise Server account to Jira Software, you must use the DVCS Connector provided in Jira. You'll need admin permissions on both Jira Software and the GitHub Enterprise account you want to link. 

To integrate correctly, the DVCS Connector must be able to call your GitHub Enterprise Server. Please speak to your network admin to make sure the GitHub Enterprise Server is available to be called from Atlassian’s IP addresses. Doing this requires opening a hole in your firewall, which might not be acceptable to some security teams. Reverse proxies are currently not supported by DVCS. We’re working on an alternative solution to connect GitHub Enterprise Server accounts to Jira Software while running behind the firewall. Learn more about IP addresses for Atlassian cloud products.

GitHub Enterprise Server doesn’t support the authorization of Personal Access Codes through SSO. This means that even if your network admin allows traffic from Atlassian IP addresses, DVCS will fail to connect to your GitHub Enterprise Server installation. This limitation will remain until the GitHub Enterprise Server team introduces the same mechanic they provide for GitHub Enterprise Cloud.

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. Navigate to Settings > Developer settings > OAuth apps

  3. Choose New OAuth App

  4. Enter a name for Application Name

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

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

Screen to add new GitHub Enterprise account showing required fields

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.

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:

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

Learn more about integrating with development tools

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. Learn more about managing project permissions.

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.

Additional Help