Keelcroft / GitHub Issues Sync for Jira

GitHub Issues Sync for Jira

Keep a Jira issue and a GitHub issue in step, and prove it.live on Atlassian Marketplace

What it does

A Jira project administrator connects one Jira project to one GitHub repository, chooses which fields travel in which direction, and links existing issues or enables an automatic-creation rule. A change on either side is then carried to the other, verified, and recorded.

• Title, open or closed state, and labels, in either or both directions.
• Optional plain-text descriptions and explicit Jira account ID to GitHub login assignee mappings. The first GitHub assignee is managed; additional assignees are kept, and unassignment is blocked if it would remove them.
• Optional issue creation in either or both directions. Without a trigger label, only issues created after sync was enabled qualify; with a trigger label, matching older issues can qualify too.
• Optional copying of new comments added after linking, with source author names and markers. Restricted/internal Jira comments and pull-request comments are excluded; edits and deletions are not mirrored.
• A reconciliation view listing every linked pair with its agreement state, how long ago the pair was last proven identical, and a replay button for anything out of agreement.
• A setup check that creates a disposable GitHub issue, reads it back, verifies the title and closes it again.
• Read-only, admin-only Check connection: repository access, webhook active state, required events, TLS verification and GitHub's last delivery HTTP status.
• Admin Repair webhook on an enabled connection, using its stored signing secret without resetting mappings, the enable boundary or linked pairs.
• Per-project scoping, pause and confirmed unlink from Reconciliation. Unlink removes neither issue; a matching trigger label may relink it unless you remove the label or change the rule.

How verification works

Writing a field and assuming it landed is the usual reason a sync quietly drifts. This app does not assume.

• It reads both sides and works out which fields actually changed.
• It writes only those fields.
• It then issues a separate read against the platform it just wrote to, and compares the stored values with what it asked for.
• The outcome, including any field the platform refused to store, is recorded against the pair and shown in the reconciliation view.

Labels are compared as sets, because Jira reorders them on write. Every inbound webhook delivery is checked against its HMAC-SHA256 signature before the body is parsed. Forge delivers at least once, so jobs are serialized per connection and repeated deliveries stop when their durable event is already complete.

What it deliberately will not do

• It never deletes an issue on either side. If one side of a pair disappears, the pair is marked failed and the surviving record is left alone.
• It never overwrites an edit silently. Edits on both sides are applied in both directions when they touch different fields. A real collision is resolved by the policy you chose and the losing edit is always reported. If both sides changed at the same instant, the pair is held as a conflict rather than guessed.
• It never writes a status it was not told about. An unmapped Jira status is reported to you instead of being forced onto the issue.
• It never rewrites a label to make it fit. GitHub labels may contain spaces and Jira labels may not, so an unsupported label produces a generic warning rather than being retained or silently hyphenated.
• It does not relay your data through our servers. Jira talks to GitHub directly from Atlassian Forge. There is no vendor-hosted middleman.

Current limits

• GitHub has two states. Several Jira statuses can map onto open; translating back picks the first Jira status mapped to that state, so the reverse direction is deterministic but not always the status you were on.
• Description sync is off by default. GitHub issue bodies are Markdown, which this app carries verbatim. Jira will display it as plain text rather than rendering it.
• Assignees require explicit mappings. An administrator supplies Jira account IDs and GitHub logins. These are stored personal data; the app does not search the user directory.
• One Jira project to one GitHub repository.
• Comments are bounded, not an unlimited archive. Each pass reads up to five pages of 100 comments from each platform and pauses copying if history is incomplete. At most 10 comments per direction are copied per pass; source text beyond 30,000 characters is visibly shortened. Later work needs another pass, not a guaranteed catch-up time.
• Comment settings are explicit. New connections default to both directions; legacy connections with no comment setting stay off on save unless an administrator enables them.
• No rich-text conversion, files/attachments, native priority or arbitrary custom fields.
• Health is a snapshot, not continuous monitoring. A successful last webhook delivery does not prove a sync completed. Repair checks at most five pages of 100 hooks and refuses incomplete enumeration rather than risking duplicate hooks.
• Recovery needs administrator action. Non-retryable GitHub 401/403 errors without a retry delay stop with a failed, replayable pair. Restore token/access, check or repair the webhook, then replay. Transient errors such as 503 and rate limits use bounded retries, not unlimited attempts or guaranteed latency.
• Pause is not data deletion. It clears the webhook signing secret, not the stored token, mappings, links or history. There is no general disconnect/delete-connection control.
• The setup check closes its disposable issue rather than deleting it. GitHub's REST API cannot delete an issue.
• Runs on Atlassian does not apply. Any app that talks to a third-party API needs egress, which makes that badge unavailable by definition.

The October 27 developer test verified both creation and comment directions, a GitHub title/plain-body update to Jira, explicit assignment/reverse unassignment, exclusion of an actual role-restricted Jira comment after replay, health and mapping/link-preserving repair. It did not establish teammate permissions, throughput under load or GitHub Enterprise Server behavior.

What you need to connect

• A GitHub fine-grained personal access token scoped to the repository, with Issues (read and write), Metadata (read) and Webhooks (read and write).
• Jira project administrator rights on the project you connect.
• For GitHub Enterprise Server, your Atlassian organisation admin adds your host through Atlassian's customer-managed egress controls. This configuration path exists, but live Enterprise Server behavior remains unverified.

Start with one issue pair

1. Install the Marketplace app, then open a company-managed Jira project's settings, Apps, GitHub Issues Sync for Jira.
2. Enter the GitHub owner and repository as separate names. Save the connection first; the token section then appears.
3. Enter a repository-scoped token directly into the app and choose Store token. A cleared input with Token stored is expected. Never email the token.
4. Run the setup check, then choose Turn on two-way sync to register the signed repository webhook.
5. Create or select an existing issue on each side. Link the Jira issue key and GitHub issue number, then check Reconciliation.
6. Change the title on one side and independently verify it on the other; repeat in the reverse direction after the first edit settles.

For a first title-only test, leave description sync off and status sync off until you have selected valid status mappings. Enable auto-create, comments or explicit assignees only if you want those flows. Get troubleshooting and guided setup help.

Support

Email support@keelcroft.com. Security reports: same address, subject line “Security”.

GitHub is a trademark of GitHub, Inc. Keelcroft is an independent publisher and is not affiliated with, endorsed by, or sponsored by GitHub, Microsoft or Atlassian.