How to use Gogs: install and run your own Git server

What Gogs is and who it suits

Gogs is a self-hosted Git service. Its stated goal is to be a simple, stable and extensible service that can be set up in the most painless way. It is written in Go, so it ships as an independent binary distribution across platforms that Go supports, including Linux, macOS, Windows and ARM-based systems.

It is a good fit for small teams that want a private Git server on their own hardware, hobbyists running a home server or Raspberry Pi, and people who prefer not to host code on a third-party platform. It is not a fully managed hosted service, so you install and maintain it yourself.

Get the Gogs source

The source is available from the official repository. Clone it with the command below. The README points to the project homepage, gogs.io, for user documentation and to the installation guide for setup steps.

Choose hardware and a database

The project says a Raspberry Pi or a $5 DigitalOcean Droplet is more than enough to get started. For teamwork, the README gives 2 CPU cores and 512MB RAM as the baseline, and says to increase CPU cores when the team grows significantly, since the memory footprint remains low.

For the backend, Gogs supports PostgreSQL, MySQL, MariaDB and SQLite3, as well as any database backend that speaks one of those protocols.

• Small or personal use: a Raspberry Pi or small VPS is the project's stated starting point.
• Team use: plan for 2 CPU cores and 512MB RAM as a baseline, then add CPU as the team grows.
• Browser: the smallest officially supported resolution is 1024*768. Browser versions are listed on the Semantic UI page linked from the README.

Use the core features

Gogs covers the everyday parts of a code host. You can manage users, organizations and repositories, and access repositories over SSH, HTTP and HTTPS. Repositories include issues, pull requests, a wiki, protected branches and collaboration tools.

Other features include webhooks (including Slack, Discord and Dingtalk), Git hooks, deploy keys, Git LFS, migration and mirroring of repositories from other code hosts, and a web editor for quick file and wiki edits. Authentication can use SMTP, LDAP, a reverse proxy, GitHub.com or GitHub Enterprise with 2FA.

Know the limits before you commit

The API is experimental. The README points to API documentation but describes support as experimental, so do not plan on a complete GitHub API replacement. Check the documentation for what is covered.

Installation is also on you. There is no managed option described in the source, so backups, updates and security are your responsibility. Ready-made deployment options named in the README include Cloudron, YunoHost and alwaysdata, plus a Docker route on Synology.

Get help and find community resources

For problems, the README points to a troubleshooting page on gogs.io and to GitHub Discussions. The README also links several community tutorials covering Raspberry Pi, Docker, Ubuntu and FreeBSD setups. Check their dates and versions yourself before following them.