Gitea: self-hosted Git hosting that reuses GitHub Actions workflows

What Gitea replaces, and for whom

The README states the goal plainly: to make the easiest, fastest, and most painless way of setting up a self-hosted all-in-one software development service. The list that follows is the real scope of the project. Git hosting, code management, code review, issue tracking, project kanban, wiki, team collaboration, a package registry, and CI/CD that can reuse GitHub Actions.

The audience is narrower than that sentence suggests. Gitea targets teams that already run their own servers and want the forge to be one more service they control, not a SaaS dependency. If your organisation cannot send source code to a third party, or you want the same instance to serve a small group on a NAS and a build fleet on a rack, the single-binary model is the argument. If you want someone else to run the runners, patch the database and answer the pager, this is the wrong shape of product.

The project is written in Go, and the README claims it works across all the platforms and architectures that Go supports, naming Linux, macOS, FreeBSD/OpenBSD and Windows on x86, amd64, ARM, RISC-V 64 and PowerPC. That portability is a consequence of the language choice, not a separate feature. It is also the reason the official image and a bare binary are both plausible deployment paths.

One Go binary, one database, and a runner you add yourself

The repository layout shows a conventional Go application: main.go at the root, with models/, modules/, cmd/ and options/ beside it. The build produces a binary that the README says you start with ./gitea web, or inspect with ./gitea help. That binary serves the web UI, the Git HTTP transport, the API and the internal job queue. There is no separate application server to wire up.

The Dockerfile shows how the official image is assembled. The frontend is built on the native platform, then the backend is compiled for each target platform with the tags bindata and timetzdata, so templates and assets are compiled into the binary and timezone data travels with it. The final stage is Alpine and exposes ports 22 and 3000. Port 3000 is the web interface; port 22 is the built-in SSH server for Git over SSH.

CI is the piece that is not inside that binary. Actions run on a separate runner process, which the README lists among the official projects alongside the go-sdk and the tea CLI. The README also notes that Gitea Actions can reuse GitHub Actions, which is a compatibility claim about workflow syntax rather than a promise that every action in the marketplace will work.

Installing Gitea with Docker and running a first workflow

The README points at the official image on Docker Hub for container deployment, and the Dockerfile confirms the exposed ports. The Dockerfile documents the two ports the image listens on:

EXPOSE 22 3000

Port 3000 is the web interface and port 22 is the built-in SSH server for Git over SSH. The README names the image as gitea/gitea and says you can use a container (docker/podman/etc) to deploy on your own server. It does not print a full run command, so take the flags, volume mounts and environment variables from the image's own documentation rather than inventing them here. After the container starts, the first visit to the web interface shows the installation page where you choose the database.

Configuration has two layers, and the README's own FAQ separates them. Dynamic options are changed in the admin panel's configuration section. Static options live in app.ini, and editing them requires a restart. The repository keeps a fully commented example at custom/conf/app.example.ini, and the README points to the configuration cheat sheet in the documentation for the keys themselves.

Once the instance is up, the practical next step is CI. Install a runner from the official runner project, register it against your instance, and add a workflow file to a repository. The README does not reproduce the runner's registration commands, so take those from the runner's own documentation. What the README does establish is the reuse claim: workflow files written for GitHub Actions are the intended input format, which is what makes migration from a hosted forge plausible at all.

For command-line work, the README names tea as the official CLI. It is a separate project, not a subcommand of the server binary, so ./gitea help will not list it.

Where the all-in-one model costs you

The single binary is also a single point of failure. Everything the instance knows lives in its data directory and its database, and the README does not document rollback. There is no described procedure for reverting an upgrade, which means your recovery plan has to be a restore of the database and the data volume taken before you upgrade. Teams that treat upgrade as a routine package update will eventually learn this the hard way.

Actions compatibility is the second soft spot. Reusing GitHub Actions means the workflow syntax is familiar, but the runner is a separate project with its own coverage of action features. A workflow that depends on hosted-runner specifics, or on an action that assumes the hosted platform's environment, can fail in ways the server logs will not explain. The README states the reuse goal; it does not publish a compatibility matrix.

Scale is a design boundary rather than a bug. The project's framing is a self-hosted service that is easy to set up, and the deployment path it recommends is a container on your own server. If you are planning for a large multi-tenant installation with dedicated build fleets and per-team isolation, you are outside the shape the README describes, and you should be evaluating the heavier forges instead.

Gitea compared with GitLab and Forgejo

GitLab is the comparison people reach for, and the difference is architectural. GitLab ships a much larger surface: its own CI runners, container registry, security scanning and a Kubernetes-oriented deployment story. Gitea keeps the surface smaller and the deployment simpler, which is why a Go binary and an Alpine image are enough. If you need the scanning and the managed runner fleet, GitLab gives you more out of the box and asks more of your infrastructure in return. If you want review and CI without operating a platform, Gitea's footprint is the point.

Forgejo is the closer comparison, and the difference is governance rather than features. Forgejo began as a fork of Gitea, and the two share a common ancestry and much of the same interface. The practical question is which project's release cadence, decision-making and long-term stewardship you want to depend on, because a self-hosted forge is a multi-year commitment. Both are MIT-licensed and both are written in Go, so the technical migration cost between them is lower than the cost of moving to or from a hosted platform. Pick on governance, then verify the specific version you need exists on the side you chose.

Releases, upgrades and what the MIT licence leaves to you

The release history is dense. v1.27.0 landed on 2026-07-13, v1.27.1 on 2026-07-27, and v1.27.2 on 2026-08-13, which is also the date of the most recent push to the default branch. That cadence is the maintenance cost in miniature: patch releases arrive often enough that a policy of upgrading only when something breaks will leave you several versions behind.

The README gives one concrete operational habit for security work. It says to search the release log or CHANGELOG.md for the keyword SECURITY to find the security patches. That is a manual step, and it is the one the project documents. Vulnerability reports go privately to [email protected] rather than to the public issue tracker, which is stated in the contributing section.

The licence is MIT, and the README links the LICENSE file for the full text. MIT is permissive: it lets you run, modify and redistribute the software, including in commercial settings, provided the copyright notice and permission notice are preserved. What it does not do is give you any warranty or support commitment. There is no vendor obligation to fix your instance, and no compatibility guarantee across versions. That is a factual property of the licence, not legal advice; if your organisation has specific obligations around redistribution or attribution, route the question to whoever handles licensing.

Editorial conclusion

Adopt Gitea if you are comfortable operating a Go service and a database yourself and want code review, issue tracking, a package registry and CI under one roof, with workflows you can port from GitHub Actions. Do not adopt it if you need the hosted platform's managed runners, marketplace or compliance paperwork, or if nobody on the team will own upgrades. Before committing, verify three things: that the official image runs your target architecture, that your Actions workflows do not depend on features the runner does not implement, and how you will restore from a database backup, because the README does not document rollback.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes