Gogs: a single-binary self-hosted Git service in Go

What Gogs solves, and the team size it was designed for

Gogs exists to remove the operational work from running your own Git host. The README states the project aims to build a simple, stable and extensible self-hosted Git service that can be set up in the most painless way, and the Go implementation is what makes the delivery model possible: an independent binary distribution across all platforms that Go supports, including Linux, macOS, Windows and ARM-based systems. That is the whole pitch. No runtime to install, no interpreter version to match, no package manager dependency at the target machine.

The intended audience is visible in the hardware guidance rather than stated outright. The README says a Raspberry Pi or a $5 Digital Ocean Droplet is more than enough to get started, and that some deployments run in a 64MB RAM Docker container. For teamwork it names 2 CPU cores and 512MB RAM as the baseline, and says memory footprint remains low as you add CPU cores for larger teams. That is a small-team or single-operator profile. An organisation with hundreds of developers and a compliance function is not the target, and the feature list does not pretend otherwise.

The mechanism: a Go binary, a database, and a git-module dependency

The repository is a Go module named gogs.io/gogs, and go.mod declares go 1.27.0. Git operations do not shell out to a hand-rolled wrapper; the module depends on github.com/gogs/git-module v1.8.9, and the web layer is built on github.com/flamego/flamego v1.13.0 with the binding, cache, captcha, session and validator packages alongside it. Older Macaron packages still appear in the dependency list, which tells you the HTTP layer has been migrated in stages rather than rewritten in one pass.

State lives in a relational database. The README lists PostgreSQL, MySQL, MariaDB, SQLite3, or any backend that speaks one of those protocols. The SQLite path pulls in github.com/glebarez/sqlite v1.11.0, a pure-Go driver, which is consistent with the single-binary claim: no cgo SQLite build step is required for the default embedded option.

The front end is a separate build. package.json declares [email protected] and the workspace is private, with the web assets under web/ and the build output landing in public/dist. The Dockerfile reflects that split directly: a node:24-alpine stage runs pnpm install --frozen-lockfile and pnpm --filter gogs-web run build, and the Go stage copies the result in with COPY --from=webbuilder /src/public/dist ./public/dist before compiling ./cmd/gogs. If you build from source rather than pulling an image, you have to reproduce that two-stage order yourself.

Installing Gogs with Docker and reaching the first repository

The README does not inline installation steps. It says: "Please follow the guide in our documentation" at gogs.io/getting-started/installation. So the facts below come from the Dockerfile in the repository, not from a README walkthrough, and the image is what the project itself builds.

The container exposes ports 22 and 3000 and declares two volumes, /data and /backup. The environment variable GOGS_CUSTOM is set to /data/gogs in the image, so the custom configuration directory lives inside the mounted data volume. The entrypoint is /app/gogs/docker/start.sh and the default command runs s6-svscan against /app/gogs/docker/s6/, which is how SSH and the web process are supervised together. The Dockerfile's healthcheck is a curl against http://localhost:3000/healthcheck, which is the endpoint to poll if you script the startup.

VOLUME ["/data", "/backup"]
EXPOSE 22 3000
HEALTHCHECK CMD (curl --noproxy localhost -o /dev/null -sS http://localhost:3000/healthcheck) || exit 1
ENTRYPOINT ["/app/gogs/docker/start.sh"]
CMD ["/usr/bin/s6-svscan", "/app/gogs/docker/s6/"]

Those lines are the container contract: map 3000 for the web interface and 22 for SSH, and mount /data so the configuration and repositories survive a restart. The README also points at https://try.gogs.io/gogs/gogs for trying it before installing anything, which is the lower-risk way to see the UI first.

Once you are through the installer, the README lists the protocols you can clone over: SSH, HTTP and HTTPS. It also lists repository Git hooks, deploy keys and Git LFS, so a first real use is a repository with a deploy key and a hook rather than a bare push test. The installer asks you to choose a database backend, and the supported set is the one named above.

Where Gogs is the wrong tool

The API is the clearest limitation, and the project states it itself. The README describes API support as experimental and links to a reference at gogs.io/api-reference. Experimental means the surface can move between releases, so any tooling you build against it carries upgrade risk that the project has not promised to absorb. If you need a stable, versioned API contract for automation, this is a real objection and not a nitpick.

Second, the documentation is deliberately thin. The README is a vision statement plus a feature list plus links out. Installation, troubleshooting and localization all live on gogs.io, and the repository root carries a docs/ directory whose contents the README does not summarise. There is no rollback procedure in the README, and no documented upgrade path between the release lines. You are expected to read the project's own site.

Third, the browser support statement is inherited rather than owned. The README defers to Semantic UI for specific browser versions and sets 1024*768 as the smallest officially supported resolution, adding that the UI may still look right in smaller resolutions, but no promises or fixes. On a phone or a narrow window, you are outside the supported envelope.

Finally, the release list is worth reading carefully before you pin a version. Alongside v0.14.3 and its release candidate, there is an entry labelled latest-commit-build. That is a moving artifact, not a stable tag. Deploying it means deploying whatever the main branch happened to be on 2026-01-31, which is a different risk profile from a tagged release.

Gitea is the alternative, and the difference is not only the fork

Gitea is the comparison a reader will make, and the honest framing is that Gitea began as a fork of Gogs, so the two share a lineage and a lot of surface area. The divergence is in where the effort goes. Gogs keeps its scope narrow: the README's feature list covers users, organisations, repositories, issues, pull requests, wiki, protected branches, webhooks, Git LFS, migration and mirroring, and stops there. There is no package registry, no built-in CI, no project board in the list.

Gitea's community grew around a broader feature set and a larger contributor base, which shows up as more integrations and more documentation written by people other than the original authors. If your decision hinges on ecosystem breadth or on finding a third-party guide for a specific problem, that difference matters more than any architectural point. If your decision hinges on deployment simplicity and a small dependency surface, Gogs is the leaner of the two and the Go module list above is short enough to audit.

A second alternative is not a competing forge at all: for a single developer who only needs private remotes, plain git over SSH with no web interface removes the database, the web process and the upgrade question entirely. Gogs earns its place when you want the web layer: issues, pull requests, a wiki and a browsable history.

Maintenance, upgrades and what the MIT licence leaves to you

The repository is not archived, and the last push was on 2026-01-31. The most recent tagged release is v0.14.3, dated 2026-06-07, with v0.14.3-rc.1 the day before. The gap between the last push and the latest tag is the thing to plan around: the release line and the main branch are not moving in lockstep, so reading CHANGELOG.md before an upgrade is the only way to know what a version bump contains. The README points at CHANGELOG.md for the list of changes in each release, which is where that reading starts.

The upgrade cost is mostly operational, not code. The Dockerfile pins golang:1.27-alpine3.23 for the build and alpine:3.23 for the runtime, and the runtime layer installs a specific set including "zlib>1.3.2" and "openssl>3.5.7-r0". Those constraints are part of the image, so rebuilding from source means owning them. The finalize.sh script under docker/build/ runs at image build time and is not described in the README; if you build your own image, read it.

The MIT licence is permissive and short. It lets you use, modify and redistribute the code with the copyright notice and permission notice retained. It says nothing about your data, your users or your obligations under other rules, and it is not a support contract: there is no warranty and no commitment to fix anything. If your organisation needs a support agreement or an indemnity, MIT does not provide one, and nothing in the repository suggests the project offers it.

Editorial conclusion

Gogs fits small teams and single operators who want SSH, HTTP and HTTPS Git hosting on one binary and are willing to read the project's own site when the README runs out. It is the wrong pick if you need a documented API contract, since the README calls API support experimental, or if you depend on the community ecosystem that grew up around Gitea. Verify three things before committing: that the tagged release v0.14.3 is the build you deploy rather than the latest-commit-build artifact, that the database you plan to use is one of PostgreSQL, MySQL, MariaDB or SQLite3, and that the custom directory set through GOGS_CUSTOM is the one you back up.

Frequently asked questions

Official sources

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