> ## Documentation Index
> Fetch the complete documentation index at: https://checksum.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue Tracker Sync

> Create and update Jira, Linear, or ClickUp tickets automatically when Checksum finds bugs, and keep their statuses in sync in both directions.

## At a glance

| Tracker | Tickets are created in | Set up in |
| - | - | - |
| **Jira** | A project | [Settings → Integrations](#connect-a-tracker) |
| **Linear** | A team | [Settings → Integrations](#connect-a-tracker) |
| **ClickUp** | A list | [Settings → Integrations](#connect-a-tracker) |

When a test failure is marked as a bug in Checksum, a ticket is created in the connected tracker. Status changes on either side, in Checksum or in the tracker, are reflected back to the other according to your [status mappings](#status-mappings).

<Note>
  **Tickets, not chat alerts**

  Issue Tracker Sync is separate from [notification connectors](/docs/notifications-and-slack#notification-connectors), which post one-way messages to Slack, Teams, Discord, or Google Chat. Issue Tracker Sync creates and manages real tickets in a project tracker.
</Note>

<div className="ai-ref">
  <Accordion title="Reference for AI: issue tracker sync at a glance" icon="robot">
    | Item | Value |
    | - | - |
    | Trackers | Jira (project), Linear (team), ClickUp (list) |
    | Setup location | **Settings → Integrations**, Issue Tracker Sync section (separate from Notification Connectors) |
    | Permission | Workspace **admin** role to add, edit, or remove connections |
    | Auth | OAuth consent per provider. Tokens are stored by Checksum, refreshed automatically, and never shown again |
    | Connection scope | One connection maps one Checksum application to one destination unit in one tracker. Multiple connections are allowed |
    | Outbound trigger | A test failure is marked as a bug → one ticket per bug per connection (no duplicates) |
    | Ticket contents | Title derived from the bug, bug description, severity, deep link to the bug in the web app |
    | Inbound | Tracker status change → provider webhook → HMAC signature verified → linked bug updated if an inbound mapping exists |
    | Mapping directions | Outbound only, Inbound only, Both. Unmapped statuses are skipped silently |
    | API | No public REST endpoints for tracker connections. Bugs are readable with `GET https://api.checksum.ai/public-api/v1/health-dashboard/bugs` ([List bugs](/docs/health-dashboard#list-bugs)) |
  </Accordion>
</div>

<div className="part ui"><span className="part-icon">▦</span><div><div className="part-title">In the Checksum web app</div><div className="part-sub">Connect a tracker and map statuses in Settings → Integrations</div></div></div>

## Connect a tracker

Issue Tracker Sync is configured under **Settings → Integrations** in the [Checksum web app](https://app.checksum.ai), in its own section, separate from Notification Connectors.

<Warning>
  **Admin role required**

  The workspace **admin** role is required to add, edit, or remove connections.
</Warning>

<Steps>
  <Step title="Connect a tracker">
    Find the tracker you want to connect and start the authorization flow. You're redirected to that provider's **OAuth** consent screen. Approve the requested permissions so Checksum can create and update issues on your behalf.
  </Step>

  <Step title="Choose the destination">
    After authorization, select where tickets for this Checksum application should be created: the Jira project, Linear team, or ClickUp list.
  </Step>

  <Step title="Configure status mappings">
    Map each Checksum [bug status](/docs/health-dashboard#bug-status-workflow) to a status in the tracker, and choose a [sync direction](#sync-direction) for each mapping. Use **auto-map** to get suggestions, then review them before saving.
  </Step>

  <Step title="Done">
    The connection is active. The next time a test failure is marked as a bug for that application, Checksum opens a ticket in the destination and starts syncing status changes according to your mappings.
  </Step>
</Steps>

One connection maps a single Checksum application to one destination in one tracker. You can add several connections, for example a Jira project for one application and a Linear team for another.

## Status mappings

Status mappings control which status changes cross between Checksum and the tracker, and in which direction. You can change them at any time from the connection's settings panel.

### Sync direction

Each status pair has its own direction:

| Direction | What happens |
| - | - |
| **Outbound only** | Status changes in Checksum update the tracker ticket |
| **Inbound only** | Status changes in the tracker update the Checksum bug |
| **Both** | Changes in either system are reflected in the other |

A common pattern is to map **Open → In Progress** as **Both**, so your team can work the ticket from either side, and **Done → Resolved** as **Inbound only**, so the tracker is the source of truth for closing it.

### Auto-map

Auto-map inspects the statuses in the connected tracker destination and suggests pairings by status category. For example, "done" categories map to Checksum's resolved status. Treat the suggestions as a starting point: not every tracker status has a direct equivalent, so adjust any mapping before saving.

<Warning>
  **Unmapped statuses are skipped**

  If a bug or ticket moves to a status with no mapping, nothing is propagated to the other side.
</Warning>

<div className="part bg"><span className="part-icon">i</span><div><div className="part-title">How it works</div><div className="part-sub">What syncs in each direction, and troubleshooting</div></div></div>

## What syncs

### Outbound: Checksum → tracker

When a test failure is **marked as a bug** in Checksum, a ticket is created in the connected destination. Each ticket includes:

* A **title** derived from the bug
* The bug's **description**
* The bug's **severity**
* A **deep link** back to the bug in the Checksum web app

When the bug's status changes in Checksum and an outbound mapping exists for that status, the ticket is transitioned in the tracker. Each bug is linked to at most one ticket per connection, so duplicate tickets are never created.

### Inbound: tracker → Checksum

When a ticket's status changes in the tracker, the provider sends a webhook to Checksum. Checksum verifies the payload signature (HMAC), finds the linked bug, and updates its status if an inbound mapping exists for that change.

<Info>
  OAuth tokens are stored securely by Checksum and refreshed automatically. They're never displayed back to you after the initial authorization.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No ticket was created after a bug was found">
    The test failure wasn't marked as a bug in Checksum, or no connection is configured for that application.
  </Accordion>

  <Accordion title="A ticket was created, but status changes don't reach the tracker">
    The status that changed has no outbound mapping, or its direction is set to **Inbound only**.
  </Accordion>

  <Accordion title="Tracker status changes don't update the Checksum bug">
    The mapping's direction is set to **Outbound only**, or the provider's webhook isn't configured or lacks permissions.
  </Accordion>

  <Accordion title="The connection shows an error after it was working">
    The OAuth authorization may have been revoked in the tracker. Reconnect from **Settings → Integrations** to authorize again.
  </Accordion>

  <Accordion title="What happens when I delete a connection?">
    All sync for that destination stops from then on. Tickets already created in the tracker aren't deleted.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Feature Health Dashboard" icon="chart-line" href="/docs/health-dashboard">
    Triage bugs and follow their status workflow.
  </Card>

  <Card title="Notifications & Slack" icon="slack" href="/docs/notifications-and-slack">
    One-way chat alerts for bugs, runs, generation, and healing.
  </Card>
</CardGroup>