Connect a Gitea repository

Turnstone connects to a Gitea host through an OAuth2 application that you create on that host. An owner of your Turnstone organisation adds the host once. After that, owners and admins can connect its repositories.

Add the host

To add a host, you must be an owner of your Turnstone organisation. You also need a Gitea account that can create an OAuth2 application.

1. In Gitea, create an OAuth2 application. Set its redirect URI to https://turnstone.cloud/auth/gitea/callback.
2. Copy the client ID and the client secret that Gitea shows.
3. In Turnstone, open your organisation's Settings and select Providers.
4. Select Add Gitea host to open Add a Gitea host. Enter a display name.
5. Enter the host URL, for example https://gitea.example.com. The URL must use HTTPS.
6. Enter the OAuth2 client ID and the OAuth2 client secret.
7. If the host's certificate comes from a private or self-signed certificate authority, paste the authority's PEM certificates into CA bundle.
8. Select Add Gitea host. You should see the message "Gitea host added" and the host under Gitea hosts.

Turnstone stores the client secret encrypted and never shows it again.

Connect the repository

To connect a repository, you must be an owner or an admin of your Turnstone organisation. Your Gitea account must be able to read the repository.

1. Open the Turnstone dashboard and select New project.
2. Enter a project name.
3. Choose Gitea as the provider.
4. Enter the host name without https://, for example gitea.example.com.
5. Enter the repository as owner and name, for example acme/checkout.
6. Select Connect repository. Gitea asks you to authorise the OAuth2 application.
7. Approve the request. Gitea returns you to the dashboard, and you should see the message "Repository connected."

Turnstone syncs the repository when you connect it. Sync describes when Turnstone reads the repository again.

Access

Turnstone asks Gitea for two scopes, read:repository and read:issue. With them, Turnstone checks that your Gitea account can read the repository, and each sync reads the repository's issues, commits, and pull requests.

Turnstone stores an access token and a refresh token for the host, both encrypted. The tokens are read-only, and each sync uses them. They act with the Gitea account of the person who connected the repository.

Turnstone never writes to Gitea. It creates no issue, no comment, and no commit status. The Testkit CLI posts the commit status and the pull request comment from your CI job, with your CI job's token.

To end Turnstone's access, revoke the OAuth2 application's grant in your Gitea account settings. An owner can also select Remove host under Settings, then Providers. Turnstone does not remove a host that a project still uses. Removing the host deletes its stored client secret and tokens.