Learn more about Jira Cloud products, features, plans, and migration.
Integrate Jira Cloud with Confluence, development tools, apps, and self-hosted tools using OAuth and feature flags.
Control who has access to your Jira Cloud products and give them the right permissions to perform their role.
Learn how to set up, customize, and manage Jira Cloud projects.
Explore issues, issue types, issue custom fields, issue screens, custom field context, and issue field configurations in Jira Cloud.
Define the lifecycle of your work and learn about issue workflow schemes and the issue collector.
Learn more on how you can set up Jira Cloud for your team.
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
Install the (free) GitHub for Jira app from the Atlassian Marketplace and follow the instructions to complete the installation.
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).
Select Connect GitHub organization.
Step 2: Enter your GitHub Enterprise Server details
Select GitHub Enterprise Server as your version and then select Continue.
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
Find the GitHub organization you want to integrate with and select Connect. If your organization isn’t listed, do the following:
Select Install GitHub for Jira on a new organization. You will be redirected to GitHub.
Select the organization you want to connect and the repositories you want to give permissions to, then select Install.
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.
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.
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.
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:
Atlassian IP address ranges need allowlisting - Learn more about how the app fetches data.
GitHub Enterprise Server Edition does not currently support application access via SAML SSO. Only Github Enterprise Cloud offers this ability. Learn more about authentication with SAML single sign-on.
Reverse proxy support - GitHub for Jira does not support reverse proxies.
Self-signed certificate - There is a problem with your SSL certificate.
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:
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.
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:
Navigate to the GitHub configuration screen in your Jira instance.
Select the 3 dots to the right of the GitHub App you want to update, then select “Edit”.
Enter a new GitHub client secret, or upload a new private key (or both).
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.
I’m trying to use Smart Commits but they’re not working. What am I missing?
Smart Commits make it easier for you and your team to comment on issues, transition issues, and add time tracking. To enable this for your team, check the following:
The email address in your GitHub account must match the email address in your Jira account. If you use a particular email address in GitHub and a different one in Jira, smart commits won’t work.
You must uncheck ‘Keep my email addresses private’ in GitHub. If this is checked, GitHub will not send your email address as part of the payload when a webhook is fired, causing Jira to treat this as a mismatch between emails. To update this setting in GitHub, go to Settings > Emails and uncheck the box next to **Keep my email addresses private**.
Use the correct naming when transitioning. If you want to transition an issue from one column to another, you must use the same naming for the column you want to transition the issue to. For example, if you want to flag an issue as complete and this column is called ‘Done’, you’ll need to include #done in your commit message. Alternatives like #closed or #complete won't work unless those words are in your workflow.
Don’t try to ‘jump’ columns in your workflow. If transitions aren’t working, make sure you are following the workflow set up by your team’s admin. For example, if you have three columns called ‘Todo’, ‘In progress’ and ‘Done’, but your admin has applied a rule that issues can’t be moved straight from ‘Todo’ to ‘Done’, any smart commit that tries to transition an issue from ‘Todo’ to ‘Done’ will fail. In this scenario, you need to first move your issue to #in-progress.
Enable time tracking and add it to each issue type. If you can’t see time tracking in your issues after adding something like `#time 1w 2d 4h 30m` to your commit message, ask your admin to check your site settings. Go to Settings > Issue features > Time tracking, and make sure Copying of comments to work description is set to Enabled. Your admin will also need to manually add ‘Time Tracking’ to any issue type (story/bug/task/etc) where this is to be recorded. Go to Project settings > Issue types - if ‘Time tracking’ isn’t listed under ‘Context fields’, select it in the right-hand panel and select Save changes.
It’s taking a long time to backfill my connected repositories after configuration. Is this normal?
It depends on how many repositories you are trying to backfill, and how large they are. GitHub has an hourly API limit so it can sometimes take a long time for all data to sync. To speed up backfilling, we recommend restarting the backfill from your GitHub configuration screen and specifying a date you would like to sync data from, for example, only backfill data for the past month as opposed to all historical data.
Do I have to wait for all data to complete backfilling before I can start using the GitHub for Jira integration?
No. You can start using the app with your team immediately as it starts listening and responding to webhook events (real-time data) immediately.
Why can't I see the author, reviewer names, and/or icons in my Jira issue?
In order for the author, reviewer names, and/or icons to appear in the development panel of your Jira issue, the email address associated with your Github account should match the address in your Jira account. If these two email addresses are different, then the account names and icons will not show up in Jira. This behavior is similar to smart commits, which also require matching emails.
Was this helpful?