# Connect a Gitea repository

Add your Gitea host to Turnstone, connect a repository, and see the access that Turnstone asks for.

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](https://turnstone.cloud/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](https://turnstone.cloud/docs/sync.md) 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.