---
url: /howto/connecting-version-control-system/gitea.md
description: This article describes how you can connect Teamscale to a Gitea instance.
---

# How to Connect Teamscale to Gitea

Teamscale communicates with Gitea using its REST API and webhooks.
You don't need to install plugins in Gitea or change admin settings.

:::tip General Option Reference
This guide only covers the options specific for the Gitea repository connector.
A general overview of connector options is [available here](../../../reference/connector-options/).
:::

![Screenshot of Teamscale's Gitea pull request integration](./gitea-pr-integration.png)

### Prerequisites for Gitea Integration

To integrate with Gitea, a technical user with access to the repository is needed.
The technical user can either be added directly to the repository as a *Collaborator* or to a *Team* at organization level, which allows more fine-grained permission management.
The following permissions are needed depending on the used functionality:

* Minimal permissions:
  * Read access to *Code*

* Additionally for the pull request integrations:
  * Read access to *Pull Requests* for line comments
  * Write access to *Pull Requests* for badges (findings and test gaps)
  * Write access to *Code* for voting

* For automatic webhook creation:
  * Admin access to the repository. Alternatively, you can [configure webhooks manually](#manual-creation-of-webhooks).

### Project Configuration Steps

To connect a Teamscale project to a Gitea repository, follow these steps:

[//]: # "TODO look for outdated links and fix them"

1. Ensure that the [Teamscale instance base URL](../../../reference/admin-settings/server-settings/#teamscale-instance-base-url) is configured correctly.

2. Select the **Gitea connector** during project creation.

3. Select or create an **account** for the Gitea server:

   * ***URI***: The root URL of the Gitea server (i.e., it is not repository specific).
   * ***Username***: The username of the technical user for Teamscale. Must be empty if an access token is used.
   * ***Password***: Either the password or an **access token** of the technical user with scope `write:repository`.

   To obtain an access token in Gitea, navigate to the technical user's settings page and select *Applications*.

4. Complete the configuration by providing the name of the repository including its owner (e.g. `my-user/my-repo` or `my-organization/my-repo`) and completing any other required fields.

As the first step in project creation, Teamscale will register its webhook with the repository.
After this, Teamscale will automatically be informed about events in the repository, such as pushes to the repository and changes to pull requests.

:::tip Webhook Restrictions
Since Gitea only sends webhooks to allowed hosts, you might have to add the Teamscale server to the `ALLOWED_HOST_LIST`
in the `[webhook]` section of the Gitea config (`app.ini`).

See [Gitea config cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet#webhook-webhook)
:::

### Manual Creation of Webhooks

In case the technical user does not have admin permissions to the repository, you can manually create and configure webhooks.

First, disable automatic webhook creation in Teamscale as described [here](../../configuring-post-commit-hooks/#disable-automatic-webhook-creation). Otherwise, creating the project will fail.

Then, add the webhook in Gitea:

1. Open the Gitea repository you want to add the webhook to.
2. From *Settings*, click *Webhooks*.
3. Click *Add Webhook* and select *Gitea*.
4. Configure the webhook as follows:
   * ***Target URL***: The URL of Teamscale's Gitea endpoint: `<Teamscale_baseURL>/api/gitea/web-hook`
   * ***HTTP Method***: `POST`
   * ***POST Content Type***: `application/json`
   * ***Secret***: Leave empty
   * ***Trigger On***:
     * Select *Custom Events...* with the following events:
       * Repository Events: Push
       * Pull Request Events: Pull Request
     * *Branch filter*: `*`
     * *Authorization Header*: Leave empty
5. Make sure the *Active* checkbox is checked and click *Add webhook*.