How Turnstone syncs a repository

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 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. A later sync reads the repaired block.