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

# Tracker sync

> Automatically push problem records to your connected issue tracker and keep them in sync

When sureops helps you resolve a problem, it can push the problem record to your issue tracker automatically. This keeps your team's external workflow in sync with sureops's analysis — title, status, and resolution all flow outward without manual copy-paste.

<Note>
  Tracker sync is a one-way push. sureops is the source of truth; updates made directly in your issue tracker are not reflected back in sureops.
</Note>

***

## What gets synced

When tracker sync is enabled, sureops keeps the following in step with your issue tracker:

| sureops event                        | What happens in your tracker                                                        |
| ------------------------------------ | ----------------------------------------------------------------------------------- |
| Problem record created               | A new issue is opened with the problem title, description, and AI-generated summary |
| Problem title or description updated | The corresponding issue is updated                                                  |
| Problem status changes               | The issue state/label is updated to reflect the new status                          |
| Problem marked resolved              | The issue is closed and a resolved label or state is applied                        |

***

## Who can configure this

* **Configure tracker sync:** Admins (via **Settings → Problem Tracker Config**)
* **Push problems to the tracker:** Any role with `problems:write` capability (Responder and above)

See [Roles & Capabilities](/next/administration/roles-and-capabilities) for details.

***

## Setup

<Steps>
  <Step title="Connect your issue tracker">
    Before configuring tracker sync, your Admin must enable the relevant integration. Go to **Settings → Integrations** and connect your issue tracker. The integration requires MCP access — your Admin will complete OAuth or credential setup during this step.
  </Step>

  <Step title="Open Problem Tracker Config">
    Navigate to **Settings → Problem Tracker Config** (Admin only). Select your connected tracker from the list of available providers.

    <Note>
      You can change providers later, but existing problem records stay linked to their original tracker issue — they won't be migrated automatically.
    </Note>
  </Step>

  <Step title="Configure tracker-specific settings">
    Depending on your tracker, you will be asked for:

    * **Target project or repository** — where new issues should be created
    * **Labels or tags** — applied to every issue sureops creates (helps your team filter by source)
    * **Resolved state** — which issue state or label marks a problem as closed in your tracker
    * **State mappings** — how sureops problem statuses map to your tracker's workflow states

    If you leave label fields blank, sureops applies a default `sureops-problem` label so your team can find issues easily.
  </Step>

  <Step title="Choose auto-push or manual push">
    * **Auto-push on** — every new problem record pushes to your tracker immediately on creation
    * **Auto-push off** — problems are queued for manual push; your team decides which ones to send

    You can toggle auto-push from the same settings screen. The choice doesn't affect updates — once an issue exists in your tracker, changes sync automatically regardless.
  </Step>
</Steps>

***

## Using tracker sync

### Creating a problem from an incident

<Steps>
  <Step title="Open the incident detail page">
    Navigate to the incident you want to convert into a tracked problem.
  </Step>

  <Step title="Promote to Problem">
    Click **Promote to Problem** (or **Create Problem** if no linked record exists). Fill in the problem title and description, then click **Create**.
  </Step>

  <Step title="Automatic push (if enabled)">
    If auto-push is on, the issue appears in your tracker within seconds. The problem record stores the external issue ID so all future updates go to the same issue.
  </Step>
</Steps>

### Manual push or retry

If auto-push is off, or if a previous push failed:

1. Open the problem detail page
2. Click **Push to Tracker** (or **Retry** if the last attempt failed)
3. Confirm the push — sureops creates or updates the issue in your tracker

### Resolving a problem

When you mark a problem resolved in sureops, the linked tracker issue closes automatically and the configured resolved state or label is applied. No manual action needed in your tracker.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Integration not healthy&#x22; or &#x22;MCP unavailable&#x22;">
    The integration exists but is in an error state — authentication may have lapsed or the integration service is temporarily unreachable.

    **Fix:**

    1. Ask your Admin to check **Settings → Integrations** for your tracker
    2. If the health indicator is red, disconnect and reconnect the integration to re-authenticate
    3. Retry the push from the problem detail page

    If the problem persists, contact your sureops support contact.
  </Accordion>

  <Accordion title="&#x22;Project not found&#x22; or &#x22;Repository not found&#x22;">
    The target project or repository configured in Problem Tracker Config doesn't exist or isn't accessible to sureops.

    **Fix:**

    1. Verify the project or repository name is exactly correct (check for typos, extra slashes, or URL vs. path format issues)
    2. Confirm the integration has access to the target project — check **Settings → Integrations** → your tracker's app permissions
    3. Update the configuration in **Settings → Problem Tracker Config** and retry
  </Accordion>

  <Accordion title="&#x22;Issue created but push status shows failed&#x22;">
    The issue was created in your tracker but sureops couldn't store the external issue ID. This is a transient error.

    **Fix:** Click **Retry** on the problem detail page. If the issue persists after two retries, contact your Admin.
  </Accordion>

  <Accordion title="&#x22;Push failed, retrying...&#x22; stuck">
    The system retries automatically every hour. If you see this message repeatedly:

    1. Expand the status message to see the underlying error
    2. Address the root cause (for example, re-authenticate your tracker integration if permissions were revoked)
    3. Click **Retry** manually once the issue is resolved
  </Accordion>
</AccordionGroup>

***

## Related

* [Recurrence chains](/next/problem-management/recurrence-chains) — track incidents that match the same problem pattern over time
* [Roles & Capabilities](/next/administration/roles-and-capabilities) — understand which roles can push problems to your tracker