This file will help you troubleshoot the common issues that can occur with the GitHub for Jira integration. If you're still having troubles after reading through this file, look up your problem or similar in Issues or Create a new Issue if it doesn't already exist.
- App is not responding
- Sync status not reaching complete
- Nothing showing up in Jira
- Workflow transitions are not running
- Unmapped deployment environments
After installing the integration, clicking "Getting started" in Jira can lead to a page that shows a GitHub error page with the message App is not responding. Wait or cancel.
Uninstalling and reinstalling the integration is the most common fix for this.
- Click Uninstall from the Manage Apps page of your Jira settings.
- Visit the Atlassian Marketplace and install the GitHub for Jira app.
After installing the integration, your sync status should move from PENDING to IN PROGRESS to COMPLETE.
You can check your sync status in the integration settings:
Jira Settings -> Apps -> Manage Apps -> GitHub -> Get started
| Status | Definition |
|---|---|
| PENDING | The backfilling of historical data has not started. |
| IN PROGRESS | The backfilling of historical data has started and is still in progress. Over time, more and more historical data will show up in Jira, and the integration will work for new data sent in. |
| COMPLETE | The backfilling of historical data has finished. Historical data will be displayed in Jira. |
| FAILED | The backfilling of historical data hit an error and stopped without completing. Partial historical data may appear in Jira. |
The time it takes to complete the sync will depend on the size of your GitHub organization, especially the number of commits in your repositories. Since the sync scans branches, commits and pull requests for every repository in your installation, be mindful that selecting "All Repositories" will perform a scan of every repository in your account, including forks. If your repositories have a lot of commits, the process can take hours or even days to complete.
Because everyone's repository histories are different, it's difficult to determine how long the scan should take for a specific installation, but on average the sync can process around 100 commits per second. If it's still stuck in IN PROGRESS after a few hours, please check your installation for any large repositories first and attempt a full re-sync:
- Open the GitHub Apps settings in GitHub.
- Click Configure in Jira.
- In Repository access, select only the repositories you wish to sync to Jira.
- Click Save
- Open the integration settings: Apps -> Manage apps -> GitHub for Jira -> Get started
- Under Retry, click the dropdown and select "Full", then click Submit
This will rediscover all repositories in your installation and start a new sync.
Exceeded issue key reference limit. Some issues may not be linked.
This warning is shown when a branch or commit includes more than 100 issue keys. When a branch or commit exceeds this limit, we only send the first 100. This is enforced by Jira. This doesn't impact branches or commits that are under the limit or impact the sync status.
First check that your sync status has reached COMPLETE. No information will be displayed in Jira until the status is COMPLETE.
Next check that you're adding your Jira issue keys in your commits, branches, or pull request titles. These are the only places on GitHub where you can put your Jira issue keys that will cause updates to be sent to the Jira issue.
For more information, check out Using the integration.
In order for transitions to run from your Smart Commit syntax, a permission requirement must be met.
The email address used for the commit in GitHub that has the transition in the commit message must match an email address that has permission to run the transition in your Jira instance.
You can check the email address on GitHub by adding .patch to the end of a commit URL. For example:
https://github.com/atom/atom/commit/834f8f3d73d84e98a423fe0720abd833d5ca7a87.patch
The app does a mapping between both GitHub and Jira deployments environments names. GitHub does not have a concept of "environment type" and users can name their environments whatever they like. Jira, on the other hand, expects the types of environment, in addition to the environment name. Those can only be development, testing, staging and production. We map GitHub's environments names to one of the Jira environment types. If there's no match, Jira will consider it unmapped. The mapping logic can be found here, but it simply considers a set of common values and their variations, e.g. "prod-east" and "prod-west" are considered variants of "prod".