Gogs: Painless Self-Hosted Git Service in Go
GitHub Repo
MIT
November 20, 2026 at 01:46 PM
0 views

Gogs: Painless Self-Hosted Git Service in Go

@gogsProject Author

What Gogs is

Gogs is a self-hosted Git service written in Go. Its README states the aim as "a simple, stable and extensible self-hosted Git service that can be set up in the most painless way", distributed as "an independent binary" for every platform Go supports, including Linux, macOS, Windows and ARM. The binary prints its own one-line description when asked for help: "A painless self-hosted Git service".

The audience is small teams, homelabs and organisations that want repositories, issues, pull requests and a wiki on their own hardware without running a large stack. The README's hardware section says a Raspberry Pi or a $5 droplet "is more than enough to get you started" and names "2 CPU cores and 512MB RAM" as the baseline for teamwork. Gogs covers Git hosting and collaboration; built-in CI, package registries and similar features are listed only as "in development" on the main branch.

The repository is gogs/gogs, created on 12 February 2014, written in Go and licensed under MIT (the LICENSE file reads "Copyright (c) The Gogs Authors"). The latest release when this page was checked was v0.14.4, published on 12 November 2026. One point shapes the rest of this page: the README and docs on main describe the unreleased 0.15 development line, which differs in several important ways from 0.14.4. The hands-on section tests 0.14.4, the version most people will download.

How it works

One binary, a work directory and custom/

The release archive holds the gogs executable, the README and licence, and a scripts/ folder with service templates (systemd, launchd, supervisor, several init systems, a Windows service script) and mysql.sql. The same binary serves the web UI, the REST API and Git over HTTP, and also provides command-line tools: web, serv and hook (used internally by SSH and Git hooks), cert, admin, import, backup and restore.

The configuration primer describes two layers. The full conf/app.ini, with comments for every option, is compiled into the binary and should never be edited. Overrides go in custom/conf/app.ini, next to the binary by default or wherever GOGS_CUSTOM points. The custom/ directory also holds authentication source files, templates, locale overrides and static assets. Since 0.14.1, values can expand environment variables, such as PASSWORD = ${DATABASE_PASSWORD}.

Storage, users and processes

Repositories are bare Git repositories under [repository] ROOT, and Gogs runs the system git binary for Git operations. Metadata lives in PostgreSQL, MySQL or SQLite3. Per the 0.14.1 changelog, SQLite now uses a pure-Go driver, so building from source no longer needs CGO. SSH can go through the system OpenSSH server via authorized_keys and gogs serv, or through a built-in SSH server.

The shipped config sets RUN_USER = git, with the comment that on non-Windows systems "it should match the value of $USER environment variable". Gogs enforces this when it starts, as the hands-on section shows. The bundled systemd unit therefore runs as git and sets Environment=USER=git HOME=/home/git.

Release lines

The release-strategy page says Gogs follows semantic versioning from 0.12.0, keeps a release/ branch per minor version, and supports upgrades across only one minor version at a time. Anyone on a version below 0.12 must stop at 0.12 first. SECURITY.md says only the latest minor version (currently 0.14) gets vulnerability patches.

Key features in 0.14.4

The list below follows the README shipped inside the 0.14.4 archive, which is identical to the README at the v0.14.4 tag. The last item comes from the shipped app.ini and the CLI help instead:

  • Git over SSH, HTTP and HTTPS, with deploy keys, server-side Git hooks and Git LFS.
  • Collaboration: issues, pull requests, wiki, protected branches and collaborators, plus users, organisations and teams.
  • Migration and mirroring of repositories, including wikis, from other code hosts.
  • Web editor for quick edits to repository files and wiki pages.
  • Rendering of Jupyter notebooks and PDFs.
  • Webhooks for repositories and organisations, with Slack, Discord and DingTalk formats.
  • Authentication via SMTP, LDAP, reverse proxy and (in 0.14.x) GitHub.com or GitHub Enterprise, with two-factor authentication.
  • Databases: PostgreSQL, MySQL or SQLite3, "or any database backend that speaks one of those protocols".
  • Localisation in over 31 languages via Crowdin.
  • Operations: Prometheus metrics (a [prometheus] section, enabled by default), command-line admin tasks, and backup and restore that the help text calls "portable among all supported database engines".

The README on main goes further: Git protocol v2, SHA-256 repositories, passkeys, code search, a command palette, OpenTelemetry tracing and squash merges. These are 0.15.0+dev changelog entries, not 0.14.4 features. It also marks Actions, packages, OAuth 2.0, OpenID Connect and SAML as "in development".

Getting started

Binary releases come from GitHub releases or dl.gogs.io. Per the installation docs, after extracting the archive the server starts with:

gogs web

On 0.14.4, the first visit redirects to a web installer at /install that writes custom/conf/app.ini. The docs on main say the installer has been removed there and an app.ini is required. Admin users can also be created from the command line; the installation docs give:

gogs admin create-user \
  --name admin \
  --password ${PASSWORD} \
  --email [email protected] \
  --admin \
  --config custom/conf/app.ini

For Docker, the 0.14.4 tree ships two images. The legacy image, which its own README says "lacks modern security best practices" and will be removed no earlier than 0.17.0:

docker run --name=gogs -p 10022:22 -p 10880:3000 -v /var/gogs:/data gogs/gogs

And the next-generation image, which runs as UID 1000 without a process supervisor:

mkdir -p /var/gogs
chown 1000:1000 /var/gogs
docker run --name=gogs -p 10022:2222 -p 10880:3000 -v /var/gogs:/data gogs/gogs:next-latest

As a systemd service, after copying and editing scripts/systemd/gogs.service:

sudo systemctl enable gogs
sudo systemctl start gogs

API access tokens are obtained with basic authentication and then sent in a header, per the API introduction:

curl -u "alice" https://gogs.example.com/api/v1/users/alice/tokens
curl -H "Authorization: token {YOUR_ACCESS_TOKEN}" https://gogs.example.com/api/v1/user/repos

Backups and restores use the same binary:

gogs backup
gogs restore --from <archive>

Hands-on: Gogs 0.14.4 on a Linux VM

Everything here was run on 20 November 2026 in a cloud VM: Ubuntu 24.04.5 LTS, Linux 6.18, x86_64, 2 vCPUs, about 7.8 GiB RAM, no swap, system Git 2.43.0. The input was the official gogs_v0.14.4_linux_amd64.tar.gz from the GitHub release (SHA-256 9ee864cb64688daf3b73cb1ea4b8e871ecf55b0630a50e12918de5ac19b258d0, computed locally because the release's checksums file returned Not Found). Gogs ran as an unprivileged user with SQLite. All timings come from one machine over loopback and are only indicative.

Archive and binary

CheckResult
Archive41,317,809 bytes, 31 entries under gogs/
Binary92,344,211 bytes (about 88 MiB), statically linked ELF, not stripped; ldd: "not a dynamic executable"
Build infogo version -m: built with go1.25.14; startup log shows build time 2026-11-12 02:31:20 UTC, commit ee8f6830
./gogs --versionGogs version 0.14.4
gogs web --helpOnly two options: --port (default 3000) and --config
gogs adminEight subcommands, from create-user to reinit-missing-repositories, matching the CLI reference

First run and the web installer

With no config, gogs web logged that custom/conf/app.ini was not found ("Ignore this warning if you're running for the first time") and redirected / to /install. The installer form was submitted with curl (CSRF token from the page, SQLite path, repository root, run user, port, main as default branch, offline mode on). Three problems came up:

  • Disabling registration needs an admin. Ticking "disable registration" without filling in an admin account returned HTTP 422: "You cannot disable registration without creating an admin account."
  • The run user needs a writable HOME. The second POST wrote app.ini, but the process exited before replying (curl saw no response). The log showed Failed to execute 'git config --global core.quotepath false' and could not lock config file /home/claude/.gitconfig: Permission denied, because that home directory belonged to root. With HOME pointed at a writable directory, Gogs wrote a .gitconfig there with user.name = Gogs, user.email = [email protected] and core.quotepath = false. Do not share that home with a person's own Git identity.
  • Installer defaults differ from the shipped config. The form pre-filled PostgreSQL, run user git and default branch master. The generated app.ini set [session] PROVIDER = file, while the embedded default is memory.

After installation, startup to the first HTTP response took 0.13 to 0.27 s over four starts. Idle resident memory was 71,644 to 72,428 KiB, about 70 MiB (68,628 KiB before installation).

Admin user, token and repository

StepResult
gogs admin create-user --name alice … --admin --config custom/conf/app.ini"New user "alice" has been successfully created!" in 0.045 s (run while the server was up; the FAQ advises stopping Gogs first)
POST /api/v1/users/alice/tokens with basic auth201 in 7.6 ms, returning {"name":"cli","sha1":"…"}
POST /api/v1/user/repos with "private":true201 in 24 ms. The response had "default_branch":"", "created_at":"0001-01-01T00:00:00Z" and "empty":false; a later GET showed the real values
Token in query string (?token=)401, as expected since 0.14.2 removed URL tokens
Anonymous GET of the private repo404, not 403, as the API docs describe
Basic auth on /api/v1/user401; basic auth worked only for the token endpoint
GET /api/v1/users/alice/tokensLists the token with a different 40-hex value from the one issued: the stored hash, not the secret

The blank default_branch and zero timestamps in the create response match an entry in the 0.15.0+dev changelog, which says the response "now reports the correct default branch, empty state, creation and update times". Until that ships, read the repository again after creating it.

Push and clone over HTTP

A local repository with 201 files (about 2.7 KB of base64 text each) and 21 commits, 1.11 MiB of loose objects, was pushed with the token as the HTTP password.

OperationWall time
First push of main into the empty repo0.34 s
Push of one more commit using the account password instead of the token0.17 s
Fresh clone (22 commits, 201 files)0.08 s
Anonymous clone of the private repoRefused with a credentials prompt

The repository's ssh_url was claude@localhost:alice/demo.git: SSH clone URLs use RUN_USER, one reason the docs expect a dedicated git account.

API response times

Each endpoint was called six times with a token. The table shows the fastest and slowest response.

EndpointStatusTime (6 runs)Notes
/user, /users/alice2001.6 to 6.8 ms133-byte body
/repos/alice/demo2002.7 to 8.0 ms
/repos/alice/demo/branches2009.5 to 18.3 ms
/repos/alice/demo/raw/main/README.md20020 to 34 ms
/repos/alice/demo/contents/README.md20021 to 94 ms
/repos/alice/demo/archive/main.zip20010.7 to 30.4 ms438,654-byte zip
/repos/alice/demo/commits200125 to 352 ms23,940-byte body
/repos/alice/demo/git/trees/main200513 to 1,083 ms201 entries, 44,000 bytes; the slowest call
/repos/search?q=demo2002.6 to 6.7 msReturned {"data":[],"ok":true}; the private repo appeared only with &uid=1
POST /repos/alice/demo/issues20118 ms
/healthcheck200-Body: * Database connection: OK
/-/metrics200-No authentication; 128 lines of Go runtime and process metrics

A burst of 500 GET /repos/alice/demo requests from 8 parallel curl processes finished in 4.37 s with all 500 returning 200. Median latency was 7.4 ms, p95 34.3 ms and maximum 112.8 ms; spawning curl probably limited throughput more than the server did. Peak resident memory (VmHWM) for the session was 105,072 kB, about 103 MiB.

One side effect: with the installer's file session provider, data/sessions held 591 files (3.3 MiB on disk) after about 590 token-authenticated API calls, roughly one file per request. By default they are kept for MAX_LIFE_TIME = 86400 seconds. Busy API clients and CI integrations can therefore pile up files until session garbage collection runs.

Backup and restore

CommandResult
gogs backup --target … --archive-name full.zip0.16 s; 880,865-byte zip with 47 entries: metadata.ini (GOGS_VERSION = 0.14.4), custom/conf/app.ini, data/avatars, one JSON file per table under db/ and a 874,561-byte repositories.zip
gogs backup --database-only0.09 s; 8,664 bytes, 40 entries
gogs restore --from full.zip into a second install (own minimal app.ini, port 3001)0.70 s, "Restore succeed!"; repositories landed in the new instance's repository root
Restored instanceStarted in 0.24 s; old token, issue and repo all present; clone HEAD 09ad73d identical to the source

Two restore findings matter for migrations:

  • Restore replaces custom/. The command moved the target's own custom/ to custom.bak and put the archived one in its place. The resulting app.ini pointed at the source instance's SQLite path, repository root, log path and port 3000. Starting the restored server without fixing it would have used the source's database. The CLI reference describes restore as importing "everything" but does not mention this.
  • A leftover custom.bak breaks the next restore, after the database is touched. Running restore again failed with rename … custom.bak: file exists, but the SQLite file's modification time and size had already changed (385,024 to 389,120 bytes). The 0.15.0+dev changelog lists a fix: "gogs restore no longer replaces the database before failing when an earlier restore left its .bak directories behind".

The archive is sensitive. It contains app.ini with SECRET_KEY, and User.json includes password hash and salt fields. Access tokens appear only in hashed form.

Root and RUN_USER

ScenarioObserved
Run as root, no configStarted and served the installer, suggesting /root/gogs-repositories as the repository root
Installer as root with run user rootAccepted; the server restarted and ran as root without complaint
Run as root with RUN_USER = gitExit 1: user configured to run Gogs is "git", but the current user is "root"
gogs admin create-user as root against the unprivileged instance's configSame fatal error; admin commands must run as RUN_USER

So 0.14.4 does not refuse root outright; it refuses any mismatch between the current user and RUN_USER. Running as root is possible but not advisable.

A docs-style minimal config on 0.14.4

A minimal app.ini in the style of the main installation docs (run mode, server, SQLite, no [security] section) still redirected to /install. Adding INSTALL_LOCK = true was enough to start, and the server then ran with the shipped default SECRET_KEY = !#@FDEWREWR&*( and an open /user/sign_up page. The main docs say Gogs "refuses to start while it is still using the unsafe default"; 0.14.4 does not. In 0.14.4 the first account to register becomes admin (per the FAQ), so a reachable instance in this state can be claimed by anyone.

Use cases

  • Small-team or homelab Git hosting. One process, SQLite and about 70 MiB of idle memory in the test above fit a small VM or single-board computer. The README cites a Raspberry Pi.
  • Private mirrors of external repositories, using migration and mirroring to keep internal copies of upstream code.
  • Git behind an existing reverse proxy. Gogs listens on plain HTTP (on 0.0.0.0:3000 by default, as observed), so TLS usually comes from Caddy, nginx or Traefik. The docs include a reverse-proxy page, and the troubleshooting guide covers an nginx IPv6 localhost delay.
  • Webhook-driven CI with external tools. Gogs has no built-in CI in 0.14.4. The README lists a Jenkins Gogs webhook plugin, and generic webhooks work with other runners.
  • Scripted provisioning. gogs admin create-user, API tokens and the repository API let a script set up users and repositories, as in the test.
  • Container deployments with the next-generation image, which is designed for restrictive Kubernetes security contexts (non-root, all capabilities dropped).

How Gogs compares

Descriptions come from each project's README and licence as read on 20 November 2026; none of the alternatives were run here. Forgejo is left out because its repository on Codeberg could not be reached from the test environment.

ProjectScope per its READMEBuilt-in CI and packagesLicence
Gogs 0.14.4"A painless self-hosted Git service": hosting, issues, pull requests, wiki, webhooksNo; listed as "in development" on mainMIT
Gitea"self-hosted all-in-one software development service, including Git hosting, code management, code review, issue tracking, project kanban, wiki, team collaboration, package registry and CI/CD which can reuse GitHub Actions"Yes, with a separate action runnerMIT (licence lists "Copyright (c) 2016 The Gitea Authors" and "Copyright (c) 2015 The Gogs Authors")
GitLab CEGit repositories with fine-grained access control, merge requests, CI/CD pipelines, issue tracker, issue board and wikiYesOpen core: CE "under the MIT Expat license", files in /ee proprietary, doc/ CC BY-SA 4.0
OneDev"The Unified and Autonomous Development Platform": code search and navigation, Kanban, service desk, time tracking, AI featuresYes: CI/CD jobs from a GUI, executors in containers, bare metal or VMs, built-in package registriesMIT

Gitea is the closest comparison. Its README does not call it a fork of Gogs, but its MIT licence keeps a 2015 Gogs Authors copyright line next to Gitea's own 2016 line, and it is also written in Go and started with ./gitea web. Its README claims a much broader scope, including Actions-compatible CI/CD and a package registry, and a hosted Gitea Cloud trial. Gogs suits teams that only want Git hosting and collaboration; Gitea suits teams that also want CI and packages in the same service.

GitLab CE is a much larger platform: its README recommends installing via Omnibus packages and says EE adds features "more useful for organizations with more than 100 users". OneDev combines Git hosting with CI/CD, issue workflow automation and AI features, and supports Linux and Windows on amd64/arm64 and macOS on Apple Silicon. Both are better choices when integrated CI matters more than a small footprint.

For keeping secrets out of repositories, whichever host is used, see Gitleaks.

Limits, trade-offs and when not to use it

  • No integrated CI/CD or package registry in 0.14.4. If pipelines next to the code are a requirement, Gitea, GitLab CE or OneDev fit better on paper.
  • The README and docs describe a version not yet released. Passkeys, code search, protocol v2, SHA-256 repositories, removal of the web installer, registration disabled by default and main as the default branch are 0.15.0+dev changes. Read the v0.14.4 tag's README and the release changelog for what is installed.
  • Insecure defaults on 0.14.4. As observed: registration is open, the server listens on all interfaces, /-/metrics needs no authentication ([prometheus] ENABLE_BASIC_AUTH = false by default), and a hand-written config without a SECRET_KEY runs on the published default key. Set DISABLE_REGISTRATION, a real SECRET_KEY, a bind address and metrics auth before exposing it.
  • A heavy security-fix history. The changelog lists 12 security fixes in 0.14.4, 22 in 0.14.3, 6 in 0.14.2 and 4 in 0.14.1, covering SSRF, stored XSS, argument injection, path traversal and remote code execution, plus 11 more queued for 0.15. The fixes are good, but patches matter: only the latest minor line is supported, and upgrades must go one minor version at a time.
  • Operational sharp edges seen in testing: RUN_USER must match the user running the binary, including for admin commands; that user needs a writable HOME; restore overwrites custom/ with the source config; and a leftover custom.bak makes a second restore touch the database before failing.
  • API rough spots. The API docs call it "still in its early stages", and "Content and endpoints are subject to change". Observed: zero values in the create-repository response, search hiding the caller's own private repos unless uid is passed, and a tree listing of 201 entries taking 0.5 to 1.1 s.
  • Breaking changes are coming. The 0.15.0+dev changelog removes the web installer, MSSQL, memcache, the gogs cert command, DSA keys, Gravatar and GitHub authentication sources, and requires Git 2.43.1 or newer. The test VM's Git 2.43.0 worked with 0.14.4 but would fall below that minimum. The legacy Docker image moves to legacy-latest from 0.16.0.
  • Documentation mismatches found: the main installation docs say an app.ini is mandatory and the default secret is refused, but 0.14.4 starts the installer and accepts the default key. The CHANGELOG.md at the v0.14.4 tag stops at a 0.14.0 heading; notes for 0.14.1 to 0.14.4 exist only in the copy on main. The legacy Docker README at the tag says latest is built from main, while the main changelog says latest now points to the highest stable release.

Security reporting and support

SECURITY.md says that since 9 November 2023 vulnerabilities are accepted only through GitHub Security Advisories, in plain English and reproducible on the latest main commit. Patch releases go to supported versions, and advisories are published 14 days after the release. The policy notes that "Not all accepted GHSA are published." Help is available through GitHub Discussions and the troubleshooting docs; the docs are built with Mintlify and published at gogs.io, with sources under docs/ in the repository.

For other self-hosted infrastructure pages, see Docker Compose for multi-container setups (for example Gogs with PostgreSQL) and Uptime Kuma, which can poll the /healthcheck endpoint.

Project activity

Checked 20 November 2026: latest release v0.14.4, published 12 November 2026, licence MIT, per the GitHub releases page and the repository's licence file. The gogs/gogs repository had about 48,000 stars (47,959 at the time of writing) and 5,080 forks. It is written in Go, was created on 12 February 2014 and develops on main, which was pushed to on 20 November 2026 and carries the 0.15.0+dev line. Its go.mod declares Go 1.27.0 on main and Go 1.25.0 at the v0.14.4 tag. Release notes are in the changelog, and documentation is at gogs.io.

Enjoying this project?

Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.

Project
gogs
Created
November 20
Last Updated
November 20, 2026 at 01:46 PM

Maintain Gogs: Painless Self-Hosted Git Service in Go? Add the badge to your README

Show that the project is featured on TechLogHub and send readers to this write-up.

Featured on TechLogHub
[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/gogs?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)

Find more projects like this

One email a week: new and trending developer tools, fresh comparisons, and what shipped. Unsubscribe in one click.