• Products
  • Documentation
  • Resources

Connect a GitHub Enterprise Server account to Jira Software

This information is for GitHub Enterprise Server customers who are part of our GitHub for Jira beta trial. If you’d like to participate in the beta trial, you can register your interest here.

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

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, this page is not for you. Learn more about integrating with GitHub Cloud or GitHub Enterprise Cloud.

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

To integrate correctly, the GitHub for Jira app 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 GitHub for Jira. 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, GitHub for Jira 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: Install the GitHub for Jira App

  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 GitHub for Jira under the GitHub menu).

  3. Select Connect GitHub organization.

Step 2: Enter your GitHub Enterprise Server details

  1. Select GitHub Enterprise Server as your version and then select Continue.

  2. Enter the URL for your GitHub Enterprise Server account. This will be in the format of http(s)://<your-github-enterprise-server-domain>. Select Next.

Step 3: Create a GitHub app

Select either Automatic app creation (recommended) or Manual app creation, then select Create.

For automatic app creation, your GitHub Enterprise Server needs to be running on 2.19.18 or higher.

Automatic app creation

If you selected Automatic app creation, you'll be redirected to a page and asked to create a name for your GitHub app. Enter a name and then select Create GitHub App for <organization-name>.

When your app is created, the homepage will be set to <http(s)://<your-github-enterprise-server-domain>/github-apps/<github-app-name>. Unfortunately, the app name you entered won’t be automatically saved to your app settings. You’ll need to do this manually by going to http(s)://<your-github-enterprise-server-domain>/settings/apps/<your-github-app-name> and editing the Homepage URL to include the name of your app. Once you update this, the link should direct you to the homepage of the app that was just created.

Manual app creation

If you selected Manual app creation, you’ll need to create a GitHub App within your GitHub Enterprise Server account, copy several values from the new app into Jira, and copy several URLs from Jira into the app. Learn more about manually creating a GitHub App for GitHub for Jira.

Once an app has been created, you'll be logged in to your GitHub account.

Step 4: Connect a GitHub organization

  1. Find the GitHub organization you want to integrate with and select Connect. If your organization isn’t listed, do the following:

    1. Select Install GitHub for Jira on a new organization. You will be redirected to GitHub.

    2. Select the organization you want to connect and the repositories you want to give permissions to, then select Install.

    3. On the following screen, you’ll see the GitHub organization you just installed the app in and the name of the Jira site where you installed the GitHub for Jira app. Select Connect to confirm your connection. You will be redirected back to the GitHub configuration page in Jira.

  2. On your GitHub configuration page, you will see an IN PROGRESS backfilling status for any organizations you connected. The backfilling process might take a long time if your connected GitHub organization has a large amount of historical data. However, you can start adding issue keys to branches, commits, and pull requests, and this new data will be visible in Jira immediately.

  3. To connect more organizations, select Connect GitHub organization, then use the dropdown menu to select either Connect GitHub Cloud or Connect GitHub Server.

How the GitHub for Jira app fetches data

If you want to connect your GitHub Enterprise Server account to Jira, the GitHub for Jira app requires access to your GitHub Enterprise Server to fetch development data and send it to Jira. To do this, your network configuration must allow calls to your GitHub Enterprise Server from Atlassian’s list of IP addresses. Learn more about IP addresses for Atlassian cloud products.

The GitHub for Jira app also listens to events from GitHub Enterprise Server. This means your network configuration must allow calls from your GitHub Enterprise Server to reach Atlassian servers, specifically ones with the github.atlassian.com domain via HTTPS.

FAQs

Why can’t I connect my GitHub Enterprise Server to the GitHub for Jira app?

There are a few reasons why you might have trouble connecting your GitHub Enterprise Server account to the GitHub for Jira app:

Does the GitHub for Jira app support GitLab?

No. If you want to integrate GitLab with your Jira instance, you need to install the GitLab.com for Jira Cloud app for self-managed instances.

Can I connect multiple GitHub Enterprise Servers or GitHub Apps to Jira?

Yes. The GitHub for Jira app allows you to connect multiple GitHub servers. So you can connect more than one internal GitHub instance to a single Jira account.

You can also add multiple GitHub Apps for a connected server to connect any GitHub organizations to Jira. We recommend doing this as GitHub applies rate limits for GitHub Apps. Learn more about Rate limits for GitHub Apps - GitHub Docs

Can I create one master GitHub App in my GitHub Enterprise Server instance and connect it to multiple Jira instances?

No. A GitHub App can only be connected to one Jira instance. This is to limit access and prevent data leaks.

What’s the difference between creating a GitHub App automatically vs manually?

We recommend that you create a GitHub App automatically, as this process is relatively simple. All you need to do is enter an app name and make a few selections - we’ll use a combination of the GitHub API and a manifest file to pre-populate the app creation form for you.

If you want to create a GitHub app manually, you can do so, but the process is less simple. You’ll need to create a GitHub App within your GitHub Enterprise Server account, copy several values from the new app into Jira, and copy several URLs from Jira into the app. Learn more about manually creating a GitHub App.

I want to create a GitHub App automatically, but it says my GitHub Enterprise Server must be version 3.1 or higher. Why?

There are several reasons you might want to upgrade your GitHub version:

  1. Automatic GitHub App creation: In version 2.19.18, GitHub resolved an issue that impeded the manifest creation flow in some scenarios when a SameSite cookie policy was applied. Then, in version 3.1 support for callback_url was added, which is required by the GitHub for Jira app. You must be using version 3.1 or higher for the automatic app creation option to work.

  2. Subscribe to GitHub action events: The GitHub for Jira app subscribes to three events that are dependent upon GitHub Actions: workflow run, deployment status, and code scanning alert. GitHub Actions is available in GitHub Enterprise Server 3.0 or higher.

  3. Stay up-to-date with GitHub releases: GitHub routinely releases new versions and discontinues support for older versions. We recommend that you regularly update your server version for better performance, improved security, and new features. From September 28, 2022, version 3.2 will have discounted support, while versions 3.3 - 3.6 will have continued support and updates.

I’ve upgraded my server to version 3.x.x but I can’t see any data for workflow run, deployment status, or code scanning events.

GitHub Actions is not enabled for GitHub Enterprise Server by default. To enable GitHub Actions, follow the instructions in GitHub’s support documentation here: Getting started with GitHub Actions for GitHub Enterprise Server - GitHub Enterprise Server 3.2 Docs

How do I upgrade my GitHub Enterprise version?

Learn how to upgrade GitHub Enterprise Server.

I rotated the private key and GitHub client secret in a GitHub App in my internal instance. How do I update them in the GitHub for Jira app?

Here’s how to update your GitHub client secret or upload a new private key, or do both:

  1. Navigate to the GitHub configuration screen in your Jira instance.

  2. Select the 3 dots to the right of the GitHub App you want to update, then select “Edit”.

  3. Enter a new GitHub client secret, or upload a new private key (or both).

  4. Select Update.

Backfilling my data is taking a long time. When will I see my data in Jira?

When you conect a GitHub organization to Jira via the GitHub for Jira app, a process called “backfilling” begins. This process looks for issue keys in your historical data in GitHub. If it finds issue keys, it links your development data to existing issues in Jira.

When an organization contains a small amount of data, the backfilling process is relatively fast and may only take a few minutes. But when an organization contains a large amount of data, the backfilling process will take longer. The good news is you can start using issue keys in new branches, commits, and pull requests as soon as you’ve connected a Github organization to Jira - and this new data will be visible in Jira immediately.

 

Additional Help