Git and CI, checked 2026-10-17
Gitea: Docker configuration reference
Self-hosted Git service with issues, pull requests, packages and Actions, built for a single small server.
At a glance
Ports
Ports| Port | What listens | Source |
|---|
3000 | HTTP listener for the web UI, API and git-over-HTTP. Point the reverse proxy here. | source for port 3000 |
22 | Built-in OpenSSH daemon for git-over-SSH. Usually published on a different host port such as 222, since a reverse proxy cannot forward raw SSH the way it forwards HTTP. | source for port 22 |
Environment variables
Environment variables| Variable | Required | What it does | Example | Source |
|---|
USER_UID | No | UID the git user inside the container runs as; should match the owner of the mounted data volume. | 1000 | source for USER_UID |
USER_GID | No | GID for the git user, alongside USER_UID. | 1000 | source for USER_GID |
GITEA__server__ROOT_URL | No | Any GITEA__section__KEY variable is written into app.ini on container start. ROOT_URL sets the externally visible URL, needed when it does not match what Gitea would otherwise detect behind a proxy. | https://git.example.com/ | source for GITEA__server__ROOT_URL |
GITEA__database__DB_TYPE | No | Selects the database driver (sqlite3, mysql, postgres) when configuring via environment variables instead of the setup wizard. | postgres | source for GITEA__database__DB_TYPE |
Volumes that must persist
Volumes| Path | What is in it | Source |
|---|
/data | Repositories, the SQLite database if used, app.ini, SSH host keys and avatars. The volume owner must match USER_UID/USER_GID or the container fails to start. | source for /data |
Behind a reverse proxy
- Set server.ROOT_URL in app.ini and make sure the proxy passes Host and X-Forwarded-Proto through unmodified, or Gitea builds the wrong clone URLs. source for this reverse-proxy note
- The proxy must not decode the request URI: a request for /a%2Fb has to reach Gitea as /a%2Fb, not /a/b, or repository and package paths break. source for this reverse-proxy note
- SSH access (port 22 in the container) cannot be reverse-proxied like HTTP; it needs its own published host port, commonly 222, forwarded directly at the network layer. source for this reverse-proxy note
- Running Gitea under a sub-path is discouraged; if used anyway, the container registry needs a fixed /v2 path proxied at the domain root regardless of the sub-path. source for this reverse-proxy note
What it needs alongside it
Release timeline
Releases| Version | Date | Breaking | What changed | Source |
|---|
v28.1.0 | 2026-10-06 | No | Improves npm client compatibility and fixes several API and web handler checks, MathML markup handling and OAuth2 scope approval. | source for release v28.1.0 |
v28.0.0 | 2026-09-29 | Yes | Git network operations now route through an internal proxy with new egress settings, and RUN_RETENTION_DAYS deletes old Actions runs. Also adds security fixes. | source for release v28.0.0 |
v1.27.3 | 2026-08-29 | No | Security release restricting package token-scope access, attachment path enforcement and actions artifact verification. | source for release v1.27.3 |
v1.27.2 | 2026-08-13 | No | Security fix for collaborator access mode and httpsign, plus render and actions fixes. | source for release v1.27.2 |
v1.27.1 | 2026-07-27 | No | Security fixes for orgmode render include path and git patch apply. | source for release v1.27.1 |
If it is not coming up
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.
Other app references
All app references