Documentation

Sync Sentinel checks the GitHub to Jira sync independently of the integration that does the sync (for example GitHub for Atlassian). It proves what reached Jira, explains what did not, and repairs it in a controlled way.

1. Install and open

Install the app from the Atlassian Marketplace, then open Jira settings > Apps > Sync Sentinel. Only Jira administrators can open it.

2. Connect GitHub

Recommended: GitHub App. In Connection, enter your GitHub organization and click Create GitHub App. Open the link: GitHub shows a private, read-only app (Contents, Pull requests, Deployments and Metadata: read; events: push, create, delete, pull request, deployment, deployment status). Confirm it, then install it on the repositories to monitor. The webhook is set up automatically.

Alternative: fine-grained personal access token with read-only access to Contents, Pull requests, Deployments and Metadata (optionally Webhooks: read, so that Sync Sentinel can verify the webhook in GitHub). Paste it in Connection > Token. Then add a webhook to each repository:

• Payload URL: shown in Connection > Webhook
• Content type: application/json
• Secret: click Show webhook secret
• Events: Pushes, Branch or tag creation, Branch or tag deletion, Pull requests, Deployments, Deployment statuses

3. Select repositories and run the checks

Select the repositories, save, and click Overview > Run checks. Each check calls the real API and shows the evidence: token or app validity, rate limit, repository access, each read permission, webhook deliveries (in Sync Sentinel and, when allowed, in GitHub), the Jira Development field and project access.

4. Ledger and reconciliation

Every commit, branch, pull request and deployment that arrives by webhook or replay goes into the ledger with its issue keys and the source that saw it. Reconcile now compares, per issue, the ledger with Jira's Development field (read as you when you start it, as the app in the hourly job) and with what Jira confirmed for Sync Sentinel's own provider.

5. Diagnoses

The Overview lists diagnoses by severity, each with evidence and a fix:

• missing GitHub permissions and repositories that the connection cannot see;
• webhook problems: no deliveries, wrong secret, rejected deliveries, artifacts that only a replay found (webhook gaps), event lag;
• GitHub API rate limits;
• issue keys of projects that do not exist, issues that the app cannot find, lower-case keys, work without keys;
• artifacts that are in GitHub but not in Jira, deployments that do not reach Jira;
• history that GitHub no longer returns (for example commits of deleted branches).

6. Replay and repair

Replay re-reads one repository for a period of up to 90 days. It updates the ledger and, with Publish missing artifacts to Jira, publishes only the artifacts of issues where Jira shows fewer items than GitHub has, through Sync Sentinel's own development information provider. Publishing never moves issues through workflows (preventTransitions), never disconnects GitHub for Atlassian, and is idempotent: running the same replay again changes nothing. Use Dry run first. After publishing, Sync Sentinel reads the data back from Jira to confirm the repair. Each run shows its progress, results, skipped records with reasons, and is written to the audit log.

7. Alerts

Set thresholds for webhook event lag, webhook failures in 24 hours and artifacts missing in Jira. Alerts go to Slack (incoming webhook) and/or by e-mail through a Jira notification about an issue that you choose, to the users and groups that you choose. A cool-down avoids repeated alerts.

8. Audit log and report link

The audit log records every connection change, replay, alert and setting with time and actor. Create new report link gives a secret, read-only HTML report for change-management records.

Limits

• One Jira site connects to one GitHub organization.
• A replay covers at most 90 days and 1,000 items per artifact type; the 30 most recently listed branches are scanned for commits.
• Reconciliation checks the 150 most recently active issues per run.
• Sync Sentinel cannot change the internal queue of other integrations; its repair publishes through its own provider.