knowledge/technology/applications/web/Gitea.md

---
obj: application
website: https://about.gitea.com
---
# Gitea
Gitea is a painless self-hosted all-in-one software development service, it includes [Git](../../dev/Git.md) hosting, code review, team collaboration, package registry and CI/CD. It is similar to [GitHub](../development/GitHub.md), Bitbucket and GitLab.

![Screenshot](./gitea.avif)

## Features
- Send Webhooks on events
- Organizations with Sub-Teams
- Repositories with Issue Tracker, Pull Requests, CI/CD (Actions), Packages, Project Boards, Releases and Wiki

## Configuration
The Gitea server can be configured with the `app.ini` file.
For a list of configuration options go [here](https://docs.gitea.com/administration/config-cheat-sheet).

## Gitea Actions
Gitea Actions are available as a built-in CI/CD solution. It works just like [GitHub Actions](../../dev/GitHub%20Actions.md). You put your actions into `.gitea/workflows` inside your repository.

Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners. The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go. It is based on a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).

## Gitea Packages
A package always belongs to an owner (a user or organisation), not a repository. To link an (already uploaded) package to a repository, open the settings page on that package and choose a repository to link this package to. The entire package will be linked, not just a single version.

### Cargo Packages
Cargo stores information about the available packages in a package index stored in a [git](../../dev/Git.md) repository. In Gitea this repository has the special name `_cargo-index`. After a package was uploaded, its metadata is automatically written to the index. The content of this repository should not be manually modified.

The user or organization package settings page allows to create the index repository along with the configuration file. If needed this action will rewrite the configuration file. This can be useful if for example the Gitea instance domain was changed.

If the case arises where the packages stored in Gitea and the information in the index repository are out of sync, the settings page allows to rebuild the index repository. This action iterates all packages in the registry and writes their information to the index. If there are lot of packages this process may take some time.

To register the package registry the Cargo configuration must be updated. Add the following text to the configuration file located in the current users home directory (for example `~/.cargo/config.toml`):

```toml
[registry]
default = "gitea"

[registries.gitea]
index = "sparse+https://gitea.example.com/api/packages/{owner}/cargo/" # Sparse index
# index = "https://gitea.example.com/{owner}/_cargo-index.git" # Git

# [net]
# git-fetch-with-cli = true
```

If the registry is private or you want to publish new packages, you have to configure your credentials. Add the credentials section to the credentials file located in the current users home directory (for example `~/.cargo/credentials.toml`):
```toml
[registries.gitea]
token = "Bearer {token}"
```

Usage with cargo:
```sh
cargo publish
cargo add
cargo install
cargo yank
cargo unyank
cargo search
```

### Container Registry
Publish Open Container Initiative compliant images for your user or organization. The container registry follows the OCI specs and supports all compatible images like [Docker](../../tools/Docker.md) and Helm Charts.

To push an image or if the image is in a private registry, you have to authenticate:
```shell
docker login gitea.example.com
```

Images must follow this naming convention:
`{registry}/{owner}/{image}`

Work with Images:
```shell
docker push gitea.example.com/{owner}/{image}:{tag}
docker pull gitea.example.com/{owner}/{image}:{tag}
```

### Generic Package
Publish generic files, like release binaries or other output, for your user or organization.

To publish a generic package perform a [HTTP](../../internet/HTTP.md) PUT operation with the package content in the request body. You cannot publish a file with the same name twice to a package. You must delete the existing package version first.

```http
PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```

Example request using [HTTP](../../internet/HTTP.md) Basic authentication:
```shell
curl --user your_username:your_password_or_token \     --upload-file path/to/file.bin \     https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```

To download a generic package perform a [HTTP](../../internet/HTTP.md) GET operation.
```http
GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```

To delete a generic package perform a [HTTP](../../internet/HTTP.md) DELETE operation. This will delete all files of this version.
```http
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
```

To delete a file of a generic package perform a [HTTP](../../internet/HTTP.md) DELETE operation. This will delete the package version too if there is no file left.
```http
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
```

### Alpine Packages
To work with the Alpine registry, you need to use a [HTTP](../../internet/HTTP.md) client like [curl](../cli/network/curl.md) to upload and a package manager like apk to consume packages.

To register the Alpine registry add the url to the list of known apk sources (`/etc/apk/repositories`):
```
https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```

If the registry is private, provide credentials in the url. You can use a password or a personal access token:
```
https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```

The Alpine registry files are signed with a [RSA](../../cryptography/RSA.md) key which must be known to apk. Download the public key and store it in `/etc/apk/keys/`:
```shell
curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key
```

Afterwards update the local package index:
```shell
apk update
```

To publish an Alpine package (`*.apk`), perform a [HTTP](../../internet/HTTP.md) `PUT` operation with the package content in the request body.
```http
PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}
```

Example request using [HTTP](../../internet/HTTP.md) Basic authentication:
```shell
curl --user your_username:your_password_or_token \     --upload-file path/to/file.apk \     https://gitea.example.com/api/packages/testuser/alpine/v3.17/main
```

To delete an Alpine package perform a [HTTP](../../internet/HTTP.md) `DELETE` operation. This will delete the package version too if there is no file left.
```http
DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename}
```

Example request using [HTTP](../../internet/HTTP.md) Basic authentication:
```shell
curl --user your_username:your_token_or_password -X DELETE \     https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk
```

## Profile READMEs
To display a [Markdown](../../files/Markdown.md) file in your Gitea profile page, simply create a repository named `.profile` and add a new file called `README.md`. Gitea will automatically display the contents of the file on your profile, above your repositories.

Making the `.profile` repository private will hide the Profile README.

## Docker Compose
```yaml
version: '3.3'

services:
    gitea-server:
        image: gitea/gitea
        environment:
            - USER_UID=1001
            - USER_GID=1001
            - DB_TYPE=postgres
            - DB_HOST=db:5432
            - DB_NAME=gitea
            - DB_USER=gitea
            - DB_PASSWD=gitea
        restart: always
        volumes:
            - ./data:/data
        ports:
            - "3000:3000" # Web
            - "222:22" # SSH
        depends_on:
            - db

    db:
        image: postgres:9.6
        restart: always
        environment:
            - POSTGRES_USER=gitea
            - POSTGRES_PASSWORD=gitea
            - POSTGRES_DB=gitea
        volumes:
            - ./db:/var/lib/postgresql/data
```