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.

General Option Reference

This guide only covers the options specific for the Gitea repository connector. A general overview of connector options is available here.

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.

Project Configuration Steps

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

1. Ensure that the 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.

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

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. Otherwise, creating the project will fail.

Then, add the webhook in the 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.