Gitea vs Gogs — A Decade of Divergence from a Common Ancestor#

Summary#

Gitea was forked from Gogs in 2016. Ten years later the two codebases share the same DNA — INI configuration, urfave/cli, a built-in SSH server, Macaron-derived request context ideas — but have diverged radically in scope, architecture, and Go idiom. Gogs doubled down on its founding philosophy of simplicity and minimal operational surface; Gitea grew into a GitHub-scale platform with 20+ package registries, a CI runner protocol, and strict layered architecture. Comparing them reveals how a Go project’s early structural choices either compound into technical debt (Macaron lock-in, global database handle) or get replaced through disciplined incremental refactoring.

Comparison dimensions#

Architectural layering#

Gitea’s four-layer DAG is the single biggest architectural advantage it developed post-fork. Adding a service layer between handlers and the database allowed the codebase to scale to 500k+ lines without every feature becoming a spaghetti of route handlers calling ORM methods. Gogs’ absence of this layer is consistent with its scope but would be a serious impediment if the feature set were to expand significantly.

Narrative: The fork decision in 2016 was partly motivated by a desire for a more open development process, but the deeper architectural difference emerged gradually. Gitea contributors imposed the 4-layer rule as the project grew; Gogs chose not to, reasoning that a git hosting tool small enough to run on a Raspberry Pi doesn’t need the overhead.

HTTP framework#

Macaron’s reflection-based dependency injection is the most significant technical debt in Gogs. The framework matches middleware return types to handler parameter types at runtime using reflection — clean within Macaron’s model but completely non-portable. Migrating to stdlib net/http or chi would require rewriting every handler signature and every middleware function. Gitea made the switch (likely around 2020) and now uses chi, which aligns with stdlib and the modern Go HTTP ecosystem.

This illustrates a broader lesson: web framework choices in 2014 carried a decade-long maintenance cost. The Macaron model was clever but bet on runtime reflection instead of interfaces, making it impossible to migrate incrementally.

Database layer#

Gogs’ dual-ORM situation is the most operationally unusual aspect of the codebase. Both gorm.io/gorm and xorm.io/xorm are open connections at runtime. The DB struct (database.Handle) acts as a facade for the GORM side; the package-level engine global serves the xorm side. This coexistence is the result of a deliberate, cautious migration strategy — every new store is written in GORM, and old stores are not touched until they need to be. It is technically sound but creates cognitive overhead: a developer must know which ORM a given model uses before reading its data-access code.

Gitea committed to xorm throughout and never attempted a migration. This is arguably the simpler choice for a project of Gitea’s scale — the migration cost would be enormous — but it also means inheriting xorm’s quirks (non-standard query builder, limited generics support) indefinitely.

Async / background work#

The difference here is stark. Gitea’s WorkerPoolQueue[T any] is one of the most architecturally significant pieces of the codebase: type-safe generics, swappable persistence backends, a management API (/api/internal/manager/flush-queues), and integration with the graceful shutdown lifecycle. Every async operation — webhook delivery, search indexing, email, automerge, CI dispatch — goes through this single abstraction.

Gogs’ channel-based workers are correct for their scope but have two serious gaps: no persistence (a crash loses queued webhooks) and no graceful shutdown (in-flight work is abandoned on SIGTERM). For a small personal git server these may be acceptable trade-offs; for a team server they are significant reliability concerns.

The UniqueQueue deduplication primitive in Gogs (internal/sync/unique_queue.go) is a thoughtful design that prevents the same repository from accumulating redundant sync requests — this idea is present in Gitea too but embedded inside WorkerPoolQueue rather than as a standalone type.

API breadth and surface area#

The REST API surfaces share the same resource model (users, repos, issues, webhooks, orgs) and compatible URL patterns — this is intentional, as Gogs’ API was designed to be GitHub API v3-compatible, and Gitea inherited and extended that compatibility. Tools targeting the Gogs API generally work against Gitea’s API without modification.

The divergence is in what Gitea added:

1. Package registry (20+ native protocols). Gitea serves as a full package registry for npm, PyPI, Cargo, Maven, Helm, OCI containers, and 15+ others. Each format speaks its native protocol, meaning package managers can be pointed at Gitea without modification. Gogs has no equivalent.

2. Connect-RPC for Actions. Gitea Actions uses protobuf-over-HTTP (connectrpc.com/connect) for runner communication — strongly typed, schema-evolved, binary-encoded. Gogs has no CI runner concept.

3. Scope-based token auth. Gitea tokens carry {category}:{read|write} permissions enforced per route group. Gogs tokens are all-or-nothing (admin token or user token).

4. Private HTTP IPC. Gitea’s routers/private provides a Unix socket HTTP API for git hook subprocess ↔ server communication. This enables synchronous branch-protection enforcement during a push (before git accepts the pack). Gogs uses a subprocess model too (exec gogs hook) but communicates back to the server via simpler channel-based goroutines launched at startup rather than HTTP.

Concurrency and Go idiom modernity#

Gitea’s codebase has progressively adopted modern Go features as they became available: generics in 1.18/1.21, sync.OnceValue in 1.21. Gogs declares go 1.22 in its go.mod but has not modernized its patterns — no generics, no sync.OnceValue, no errgroup. This suggests Gogs’ Go version requirement is driven by dependencies rather than by active use of new language features.

The error-handling choice is notable: Gogs uses github.com/cockroachdb/errors for stack traces on wrapped errors — a defensible choice for a project that wants richer diagnostics, but an unusual third-party dependency that is neither stdlib nor pkg/errors. Gitea uses pure stdlib error wrapping, which is more portable and aligned with contemporary Go idiom.

Dependency injection and testability#

Both projects use manual DI, but the difference in approach is significant for testing. Gitea’s service layer functions accept explicit arguments and return typed values — even if those arguments ultimately come from singletons, the functions themselves are testable in isolation. Gogs’ handlers take *context.Context and immediately call database.Handle.SomeStore() — there is no seam to inject a mock database unless you’re testing via the newer interface-based stores.

Gogs’ mid-evolution state is visible: newer stores (UsersStore, RepositoriesStore) have comprehensive table-driven tests backed by interfaces; the legacy xorm models are tested minimally. The context.Store interface is the best engineering in the codebase — it provides a clean boundary for the auth middleware and is fully tested with mock implementations.

Configuration#

Configuration is the area of greatest similarity. Both projects chose INI files (via different but compatible libraries), both store typed config in package-level vars, and both expose the same conceptual knobs (ports, DB connections, SSH, auth sources). Gitea added environment variable overrides (GITEA__SECTION__KEY) which is a significant operational improvement for container deployments; Gogs has no equivalent.

Common patterns#

Both projects share a lineage that is visible in several consistent choices:

1. INI-based configuration with package-level typed vars. Both use gopkg.in/ini.v1-family libraries and expose config as global structs. Neither uses a modern config library like viper or functional options for application-level configuration.

2. urfave/cli v3 for the CLI. Both use the same CLI framework, and both expose the same conceptual subcommands: web, serv, hook, admin, backup/dump, restore. The flag propagation workaround (Gogs’ configFromLineage() walking cli.Command.Lineage() because v3 doesn’t auto-propagate parent flags) is a shared pain point.

3. Built-in SSH server architecture. Both run an embedded SSH server (golang.org/x/crypto/ssh) that authenticates via public key lookup in the database, then exec-dispatches to a serv subprocess which execs the git command. The two-process indirection (SSH server → serv subprocess → git) is identical in concept.

4. GitHub API v3 compatibility as a design constraint. Both REST APIs mirror GitHub’s resource model and URL patterns for users, repos, issues, and webhooks. This is a deliberate interoperability choice that has lasted a decade.

5. Table-driven tests. Both use the standard testCases := []struct{...}{ ... } + t.Run(tc.name, ...) pattern. Gitea uses it more heavily (242 occurrences vs. 95 in Gogs).

6. sync.Once for lazy initialization. Both use sync.Once to defer expensive computations (path resolution, regexp compilation, config-derived values) to first access. Gitea also uses the newer sync.OnceValue.

Divergent choices#

Scope philosophy#

This is the defining divergence. Gogs explicitly optimizes for minimal operational surface: one binary, no external dependencies required (SQLite supported), no message queues, no CI, no package registry. The README cites “painless self-hosted Git service” and deployment on low-power hardware as goals. Gitea accepted complexity in exchange for feature parity with GitHub: CI runners, 20+ package registries, federated ActivityPub (in progress), fine-grained token scopes, OCI containers.

Framework lock-in vs. migration#

Gogs remains on Macaron because the migration cost is prohibitive. Gitea migrated to chi. This is the most consequential divergence for long-term maintainability — Macaron has had no major release since 2020 and is effectively frozen. Any Gogs contributor who wants to modernize HTTP handling faces a rewrite of every handler.

ORM strategy#

Gitea stayed with xorm; Gogs is migrating from xorm to GORM. Interestingly, Gitea’s xorm usage is more mature and consistent; Gogs’ dual-ORM state is a temporary but persistent complexity. Neither project has moved to a query-builder-only approach (like sqlx or pgx), which might be considered the modern preference.

Background work persistence#

Gitea made background work persistent (LevelDB / Redis backends) with graceful shutdown; Gogs kept it ephemeral and in-memory. This reflects the scope difference: Gitea’s webhook delivery, search indexing, and CI dispatch are business-critical operations that must survive a restart; Gogs’ simpler use case tolerates some data loss.

Recommendations for practitioners#

Choose Gogs if:

• You need the smallest possible operational footprint (single binary, SQLite, no external services required)
• You run on constrained hardware (Raspberry Pi, VPS with 512MB RAM)
• Your team is small enough that the missing features (CI, package registry, fine-grained tokens) are not needed
• You want to study a Go codebase in the early-2014 architectural style (global state, Macaron, xorm) — it is historically instructive

Choose Gitea if:

• You need CI/CD integration (Gitea Actions with self-hosted runners)
• You need a package registry (replacing Artifactory, Harbor, or language-specific registries)
• You need fine-grained API token scopes for automation
• You care about reliability of background operations (webhook delivery persistence, graceful shutdown)
• You want to study modern Go architectural patterns: chi, generics, WorkerPoolQueue[T], layered architecture, graceful shutdown

For learning Go architecture:

• Gogs’ internal/database is the best example of an incremental xorm → GORM migration strategy, with the context.Store interface as a clean worked example of interface-based DI
• Gitea’s modules/queue/workerqueue.go is the best example of a practical generics application (generic type-safe background queue with swappable persistence)
• Gitea’s routers.InitWebInstalled() is the best example of an explicit, debuggable 24-step initialization sequence in a large Go application

Book angle#

The story this comparison tells is: architectural choices made in a founding week echo for a decade. Gogs chose Macaron in 2014 and is still paying that cost in 2026. Gitea chose to layer the codebase strictly and is now able to add CI runners and package registries without restructuring. Both chose INI config and urfave/cli, and those choices aged fine.

The deeper lesson is about incremental vs. discontinuous refactoring. Gogs’ xorm → GORM migration is the canonical example of doing it right: one store at a time, behind a consistent interface (Handle.Users(), Handle.Repositories()), with the old and new running side by side. There is no big-bang rewrite. The migration is invisible to callers. But the cost is a decade-long period where the codebase has two live ORM connections.

Gitea’s WorkerPoolQueue[T any] tells a different story: this is a generics retrofit of a previously interface{}-based queue system. The result is genuinely cleaner, with type safety at call sites replacing runtime type assertions. It demonstrates that Go generics, used narrowly on the right abstraction, pay for themselves immediately without the complexity cost that broad generics use would incur.

For a book chapter: use this comparison to anchor a discussion of dependency choice longevity — framework, ORM, and background-work patterns deserve more scrutiny than algorithm choices because they compound over time and are much harder to swap out.