GitHub for Atlassian integration FAQ

General questions about setting up GitHub for Atlassian

Why can't I see the author, reviewer names, or icons in Jira?

To see author, reviewer names, and icons in the development panel of your Jira work item, the email address associated with your GitHub account must match the email 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.

How can I migrate from DVCS Connector to GitHub for Atlassian?

If you’ve been using Jira’s built-in DVCS connector, you should migrate to the GitHub for Atlassian integration, as long as you meet the following requirements:

• This app officially supports http://GitHub.com (all editions including Enterprise Server) and Jira Cloud.

• Jira server is not supported.

If you haven’t already been prompted, you can manually kick off the migration:

1. Log in to your Jira Cloud account.

2. Select Settings (), then Jira apps.

3. Under Integrations in the sidebar, select DVCS accounts.

4. Follow the prompts to upgrade your GitHub connection.

Permissions requirements for GitHub for Atlassian

The permission scope for code and metadata suggests data is read to synchronize development information. Is code stored on Jira?

Commits, branches, and merges that occur in a connected GitHub repository will be seen on the dev panel in associated Jira work items. Whenever a commit message includes a work item key, it generates an event that is sent to Jira so the work item specified in the commit message can be updated. Our app needs code access to read commit messages and branch names to correctly link your data to your Jira work items, but no code is stored during this process. Our app simply sends data through to Jira.

Why does the app need metadata access to my repositories?

Read-only access to metadata is a mandatory requirement by GitHub for all GitHub apps. (Here’s more about the permissions required for GitHub apps.) This access makes it possible for GitHub apps to access various read-only endpoints for a number of resources. Our app will be able to see the repository’s code, however, Atlassian takes the security of our software very seriously. We constantly monitor our code for vulnerabilities and have processes in place to make sure it's safe to use. Additionally, GitHub documentation for metadata permissions states: “These endpoints do not leak sensitive private repository information.” If there are repositories you still don’t want our app to have access to, you can:

• select the repositories you want to grant access to when installing the app, or

• select the edit icon on the GitHub configuration page (or the “Connect an org” page) to update your GitHub settings.

Why are read and write permissions required for pull requests, contents and work items?

This is needed so our app can create links to Jira work items from pull request or work item comments. When you create a comment and include the work item key surrounded by square brackets, our app will ping Jira to see if that work item key exists in a Jira space. If it finds a matching work item, it will create a link for easy navigation. As for contents, we need the write access so we can create a branch on your request.

What happens if another change is made to the app in the future that requires new permissions? Can I choose to accept the new permission but ignore previously requested permissions that I don’t want/feel comfortable with?

Unfortunately not. GitHub apps are limited in this sense as permissions are not granular.

Smart Commits

Why aren’t my Smart Commits working?

Smart Commits make it easier for you and your team to comment on work items, transition work items, and add time tracking. To enable this for your teams you will need to make sure:

• The email address in your GitHub account matches the email address in your Jira account. For example, mypersonal@email.com in GitHub and mywork@email.com in Jira will prevent smart commits from working. However, mypersonal@email.com and mypersonal@email.com will work.

• You have unchecked '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. Jira treats this as a mismatch between emails and fails to meet the above criteria. To update this setting in GitHub, go to Settings, select Emails, and then uncheck the box next to Keep my email addresses private.

• You use the correct naming when transitioning. If you want to transition a work item from one column to another, please make sure you use the same naming for the column you want to transition the work item to. For example, if you want to flag a work item as complete and this column is called ‘Done' you’ll need to include #done in your commit message. (Words like #closed, #complete, etc, will not work unless those statuses are in fact in your workflow.)

• You aren't trying to 'jump' columns in your workflow. If transitions aren't working, make sure you are abiding by the workflow set up by your team's admin. For example, if you have 3 columns named 'todo', 'in progress' and 'done' but your admin has applied a rule that specifies work items can't be moved straight from 'todo' to 'done', any smart commit that tries to transition a work item from todo to done will fail. In this scenario, you need to first move your work item to #in-progress.

• You have enabled time tracking and added to each work item type. If you aren't seeing time tracking in your work items after adding something like #time 1w 2d 4h 30m to your commit message, ask you team's admin to check the site's settings. Here’s how to configure time tracking.

Backfilling data

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

When you connect a GitHub organization to Jira via the GitHub for Atlassian app, a process called “backfilling” begins. This process looks for work item keys in your historical data in GitHub. If it finds work item keys, it links your development data to existing work items 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 work item 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.

Do I have to wait for all data to complete backfilling before I can start using the GitHub for Atlassian integration?

Nope! The job of backfilling is to pull in all your historical data so that, if any work item keys were referenced before you installed the app, you will eventually see that data in Jira. This means you can start using the app with your team immediately as the app will start listening and responding to webhook events (real-time data) straight away.

GitHub Enterprise Server

Why can’t I connect my GitHub Enterprise Server?

Common reasons for connection problems with GitHub Enterprise Server include:

• Atlassian IP addresses need to be allowed. View the GitHub IP allowlist configuration or contact our support team.

• SAML SSO is not supported by GitHub Enterprise Server (however, Github Enterprise Cloud does support SAML SSO).

• GitHub for Atlassian does not support reverse proxies.

• Self-signed certificate (SSL) problems.

How do I update my private key and GitHub client secret in the GitHub for Atlassian app?

1. Go to the GitHub configuration page in Jira.

2. Find the GitHub app you want to update, select More actions (⋯), and select Edit.

3. Edit the GitHub client secret and/or private key, and select Update to save your changes.

Can I connect multiple GitHub Server and apps?

Yes. You can connect multiple GitHub Server to a single Jira account. You can also add multiple GitHub apps per Server to connect any GitHub organization to Jira. Read about rate limits for GitHub Apps

Can I create one primary GitHub app for multiple Jira sites?

No. Each GitHub app can only be connected to one Jira instance to maintain security and prevent data leaks.

Why do I need GitHub Enterprise Server version 3.1 to create an app automatically?

• Automatic app creation relies on support for callback_url, which was added in version 3.1.

• The GitHub for Atlassian app subscribes to three events that rely on GitHub Actions, which are available in version 3.0 or higher.

• GitHub regularly releases new versions and discontinues support for older versions. Upgrading to version 3.1 or higher will help you stay up-to-date with the latest features, bug fixes, improvements, and security updates.

To upgrade your Server, follow the instructions in GitHub’s support documentation: Upgrading GitHub Enterprise Server

Why can’t I see data for workflow run, deployment status, or code scanning events?

You may need to enable GitHub Actions in GitHub Enterprise Server. To enable GitHub Actions, follow the instructions in GitHub’s support documentation: Get started with GitHub Actions for GitHub Enterprise Server 3.2

How does GitHub for Atlassian fetch data?

The GitHub for Atlassian app requires access to your GitHub Enterprise Server to fetch development data and send it to Jira. For this to work, your network configuration must allow calls to your GitHub Enterprise Server from Atlassian’s list of IP addresses and allow calls from your GitHub Enterprise Server to reach Atlassian Server with the github.atlassian.com domain via HTTPS.

• View GitHub IP allow list configuration

• Read more about Atlassian IP addresses

Does the GitHub for Atlassian app support GitLab?

No, use the GitLab for Jira Cloud app to integrate Jira with GitLab.