Sync Jira and GitHub issues: a first-pair setup guide

First, check whether the native integration is enough

For branches, commits, pull requests and deployments attached to a Jira issue, start with the official GitHub integration. You may not need another app. A separate requirement is keeping two independently edited issue records aligned: a Jira issue and a GitHub issue, each with its own title and workflow. Those are different workflows.

Keelcroft's app connects one Jira Cloud project to one GitHub repository. It is not a multi-repository aggregator, a pull-request sync or a GitHub Projects v2 field connector.

What to prepare

• A Jira administrator who can install the app and a project administrator who can configure the chosen project.
• A repository token with Issues read/write, Metadata read and Webhooks read/write, held by a user permitted to manage that repository's hooks. Organisation policies may require approval.
• One disposable Jira issue and one GitHub issue. Use nonsensitive test content; do not start with a customer ticket or a production incident.

Enter the token directly in the app's credential field. Never put it in a support email, screenshot, issue description or recording. Plan for token expiry and replacement.

Connect, map, then link one pair

1. Open the project's app settings and save the GitHub repository connection.
2. Store the credential, run the setup check and read its result. The setup check creates a disposable GitHub issue; if it cannot be deleted, follow the reported cleanup instruction.
3. Select field directions. Start with titles and a reviewed status map; enable descriptions, comments or assignees only when you actually need them.
4. Map Jira statuses explicitly to GitHub open/closed. Several Jira statuses may map to the same GitHub state; the reverse direction uses the first configured match, not an automatic inference of the developer's intent.
5. Enable sync and link the two existing issues. Enabling the connection is not a historical backlog import.

Prove a result before relying on it

Change the title on one side, then open the other platform independently and read the title there. Repeat in the other direction. Test a mapped state transition separately. Use the reconciliation view to inspect agreement, failures or conflicts; an install or a queued job alone is not proof of a working connection.

Optional new comments copy after linking, with a source marker; edits and deletions are not mirrored. Explicit assignee maps do not imply an automatic user-directory match. The public version does not copy binary attachments, arbitrary custom fields or native Projects v2 statuses. Do not infer those candidate features from a screenshot of a development build.

If the first pair does not sync

Check the project/repository, whether sync is enabled, the token's scope and expiry, repository hook permissions and your status map. A development-panel link is not an app pair link. Resolve an actual conflicting edit deliberately before replaying; do not repeatedly relink a pair to hide a failure.

Send the setup step and a redacted error if you need help. Do not send issue content or a credential. Enterprise Server configuration is available, but has not been independently live-certified by the publisher.

Decide using your own test result

Proceed only if the app covers your required scope and your first real test works. Check the Marketplace calculator for the licensed Jira site size; the number of people in the connected project is not necessarily the billing tier. A standard evaluation is not a paid subscription or a completed rollout.

Reference: Official GitHub-to-Jira development integration. This guide describes Keelcroft's public foundational workflow and states candidate/live-testing boundaries separately; it is not a competitor benchmark or certification.