Forgejo

Last reviewed Sep 13, 2026 · 801 words

Forgejo and Gitea are, for the purposes of a Saturday afternoon install, the same product: a Go binary or one container, a SQLite file, port 3000, and a GitHub-shaped web UI on 256 MB of RAM. The difference is who controls the roadmap. Forgejo is owned by a non-profit and governed in the open by the people who run Codeberg, the largest public instance; Gitea's trademark and direction belong to a company. If that sentence makes you shrug, either works and Gitea has the larger ecosystem. If it makes you want the version that cannot be bought or relicensed under you, Forgejo is that version, and it is the one I now install by default.

The fork is now a hard fork, and that changes upgrades

Forgejo began in late 2022 as a soft fork that merged Gitea's changes and added governance. Since 2024 it develops independently: features land in Forgejo first or only, the version numbers have diverged, and there is an LTS line with a longer support window than Gitea offers. The practical consequence is that "drop-in replacement for Gitea" is no longer a promise for every version pair. Migrating from a recent Gitea release to current Forgejo is documented, but check the compatibility table on the official docs before you swap the image, because a Gitea that is newer than Forgejo's supported migration source will not import cleanly. Moving in the other direction, Forgejo to Gitea, is not supported at all. Pick once.

Our self-hosted Git forges piece and the Forgejo vs Gitea comparison go deeper on the politics; this guide stays on running it.

Install is one container and SQLite is fine for most of us

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:latest   # pin to a major tag once running
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__server__ROOT_URL=https://git.example.com/
      - FORGEJO__server__SSH_PORT=2222
    volumes:
      - ./forgejo:/data
    ports:
      - "3000:3000"
      - "2222:22"
    restart: unless-stopped

Pull the image from Codeberg, not Docker Hub, and pin a major version rather than latest so an upgrade is a decision you make. SQLite carries a personal or small-team instance (10 users, a few hundred repos) without any tuning; switch to PostgreSQL when you cross into dozens of concurrent CI jobs or you want easy point-in-time backups. Map SSH to 2222 on the host so it does not collide with the box's own sshd, and set ROOT_URL correctly on day one because clone URLs, webhooks and OAuth callbacks all derive from it.

The first web visit shows the installer; set an admin account there, then disable open registration in Site Administration unless you want a public forge. A stale Forgejo with signups open is a spam target within weeks.

Forgejo Actions runs GitHub workflows with one extra process

Actions is compatible with the GitHub Actions workflow syntax and most marketplace actions, so .github/workflows/*.yml files usually run unchanged under .forgejo/workflows/. The server does not run jobs itself; you register at least one forgejo-runner (a separate binary or container) with a token from the admin UI, and it executes jobs in Docker containers. A runner on the same 2-core VM as the forge is adequate for small projects; give it its own machine once builds compete with web requests. Labels let you route jobs to specific runners, which is how you get an ARM builder or a GPU box into the mix. If you need something heavier than that, Woodpecker CI integrates with Forgejo as well.

Federation is real work in progress, not a feature yet

The roadmap item that draws people in is ForgeFed: following repositories and receiving issues across instances the way Mastodon federates posts. Pieces of the plumbing have shipped, but as of today you cannot open a pull request from your instance against a repo on someone else's and expect it to work. Do not choose Forgejo for federation this year. Choose it for the governance and the LTS line, and treat federation as a bonus when it arrives.

What I'd do

Forgejo on a 1 GB VM with the compose file above, SQLite, SSH on 2222, registration closed, TLS from Caddy in front, nightly tar of the data directory. One runner on the same box, promoted to its own machine the first time a build makes the web UI lag. Track the LTS release, upgrade quarterly. If you already run Gitea happily and rely on a plugin or hosting integration that only knows Gitea, stay; the benefit of switching is philosophical, not functional. For a fresh install, though, the community-owned fork is the safer 10-year bet, and it costs nothing extra to make it.