# How Turnstone syncs a repository

When Turnstone reads your issues, what it reads, and what it does with an issue that has no facts.

A sync is one read of a connected repository. Turnstone reads the issues that Testkit filed and takes the facts from each issue. The dashboard's charts come from those facts. A sync writes nothing to GitHub or Gitea.

## When Turnstone syncs

Turnstone syncs a repository at these times:

- When you connect the repository to a project. This sync reads every issue that carries the `testkit` label.
- Every 5 minutes after that. This sync reads the issues that changed since the last sync.
- Once a day. This sync reads every issue again.
- When you select **Sync now**. This sync also reads every issue.

Use **Sync now** when you filed a bug or changed a label and you want the dashboard to show the change before the next scheduled sync. Owners and admins see the button.

1. Open the project.
2. In the **Issue sync** panel, select **Sync now**.

The same panel is on the project's connection settings page, under **Settings**, then **Connection**. It shows when the last sync ran and whether that sync read every issue. If a sync fails, the panel gives the reason.

## What a sync reads

Turnstone reads only the issues that carry the `testkit` label. Testkit puts that label on every issue it files. Turnstone does not read the other issues in the repository.

From each of those issues, Turnstone reads the state, the dates, the labels, and the facts block in the body. Turnstone also reads the commit that closed the issue and the commit that introduced the bug, with that commit's pull request. [Facts](https://turnstone.cloud/docs/facts.md) lists each fact and its source.

Turnstone keeps the facts. It does not store the issue's title or its text.

## Separate issues repository

Turnstone reads issues from the connected repository unless you name another one. Name another one when Testkit files your bugs in a different repository from the one that holds the code. In Testkit, `bugs.repository` in `testkit.config.ts` sets that repository.

If your `testkit.config.ts` sets `bugs.repository`, enter the same repository in the issues repository field. The field is on the project's connection settings page, and it is optional. Turnstone then reads the issues from that repository.

Turnstone needs read access to the issues repository too. On GitHub, install the Turnstone GitHub App on it.

When you change the issues repository, Turnstone deletes the facts it stored for the project. It then reads every issue from the new repository.

## Missing or invalid facts

Testkit writes a facts block into the body of each issue it files. An issue with the `testkit` label can still reach Turnstone in one of these two states:

- **No facts block.** The body has no facts block. For example, someone added the `testkit` label to an issue by hand.
- **Invalid facts block.** The body has a facts block that Turnstone cannot read. For example, an edit broke the JSON, or the block has a format version that Turnstone does not know.

Turnstone keeps the issue in both cases and records which case applies. The bug keeps the facts that do not come from the block. Those facts are its issue number and link, its state, its dates, its severity, and its area id. Turnstone takes no fact from the block, so the bug has no cause, no impact, and no introducing commit.

To repair an invalid block, edit the issue body so that the block follows the [bug record format](https://turnstone.cloud/docs/facts.md#bug-record-format). A later sync reads the repaired block.