Thoughts on a human-scale Git forge

July 15, 2024
Tags:

Despite the existence of many free software Git forges out there these days, I don’t think that any of them fit my particular niche. I think there is still room for a small, human-scale forget that is self-hostable without the side-effect of becoming a part-time sysadmin. In this post I will cover:

  • Forge essentials
  • What I use right now
  • My requirements for a self-hosted forge
  • My thoughts on how to build it

This is a bit of a spicy post, so I want to stress that this is just my opinion. I understand well that my needs are not the same as many others, which is why I find myself in this situation in the first place.

The essentials

These are the essential components of a forge:

  • Repo admin tool: Maintains a list of all the repos. Associates contributors with their SSH keys and says who has read/write access to what.

  • Repo browser: Allows repos to be explored in a web browser. Renders READMEs. Highlights code files. Display anonymous HTTP clone URLs.

  • Issue tracker: Manages bugs, feature requests, project milestones, etc. A way to get organized that is collaborative.

  • Code review tool: Gotta have that peer review. A good code review tool allows for inline comments on diffs, conversations, and a way to give something your stamp of approval. It should integrate well with the issue tracker.

  • Continuous integration: Automated building and testing so you can be confident that the code runs on two machines, at least.

My empire of dirt

Here’s what I’m using at the moment:

  • SSH access management: Gitolite. It works but it’s a weird Perl thing. I don’t much like the configuration system. I don’t have to fuss with it much, though, so it rarely bothers me.

  • Repo browser: cgit. This is a decent repository viewer, though it doesn’t look pretty. Feels odd to be using CGI applications in 2024, though. It’s written in C and that concerns me.

  • Issue tracker: Either nothing or an org-mode TODO file in the repo. This is terrible but I don’t know of anything

  • Code review tool: Email me! Terrible! I don’t want to do patch review over email, but it’s better than having to deal with some additional software what I don’t like.

  • Continuous integration: Laminar. This is the freshest piece of software in the stack. It works pretty well, honestly! I have it integrated with Guix and it makes CI easy. It’s written in C++, though.

Requirements

  1. Uses Git. Seems obvious, but if I don’t say this now people will tell me to use Fossil or Mercurial. I use Git and so does everyone else. No, I don’t want a Git-like interface to them, either.

  2. Easy to build from source with minimal dependencies. No, I will not use prebuilt binaries. I don’t care if it’s a Flatpak or a Docker container or whatever else. This means no Node, Go, Rust, and other such dependency nightmare machines.

  3. Easy to package. This builds on the previous requirement. The entire dependency tree must be easily packagable by any Linux distro. If I can’t apt install cool-git-forge I don’t want to use it. And I’m talking about from the distro’s main repository that builds from source, not some third-party repo that just bundles all the dependencies. No, I will not install anything from Flathub. Again, this means no Node, Go, or Rust.

  4. No database server. I have learned that I have no patience for database server maintenance unless I’m being paid, and I’ve done quite enough of that, thank you very much. I don’t self-host anything that requires a database server. SQLite is fine, though.

  5. Has a web interface. Should go without saying but it doesn’t! I don’t want to review patches over email! You could also call this requirement no email-based workflows.

  6. No user account management. Well, nothing beyond the unavoidable stuff like managing who can push via SSH and what their public keys are. It’s worthwhile to make an account on GitHub because it’s a giant silo, but for a personal forge it will only discourage collaboration. No one wants yet another account and I’d be stuck with usernames and hashed passwords to protect.

  7. Public issue reporting. This builds on the previous requirement. Users need to be able to file bugs without friction via a web form. They should not have to register for an account. This opens the door for spam, but spam can be mitigated.

  8. Hackable. If I’m going to host my own forge, I’d better be able to shape it like clay. It should be easy to extend any given component with custom code. A dynamic programming language is a must for this.

Out of scope

  1. Static websites. I already use my own static site generator. I don’t need this to be part of a forge.

  2. Mailing lists or forums. Too much state to manage. I don’t need it.

What about…?

Every time I complain about Git forges, I get asked about the same few projects, so let’s just go through them quickly and list the biggest reasons why I don’t want to use them.

Forgejo

Forgejo is built with Node and Go, so it doesn’t meet requirements 2 and 3.

SourceHut

SourceHut is built with Go, so it doesn’t meet requirements 2 and 3.

SourceHut uses email patch review, so it doesn’t meet requirement 5.

Guix Forge

Guix Forge comes close by pulling together a bunch of existing components. However, it lacks the cohesion that I would like. It’s close to what I use now, which mostly predates Guix Forge, with the exception of using Laminar which I can thank Guix Forge for telling me about.

Guix Forge does not include an issue tracker, so it doesn’t meet requirement 7.

Guix Forge promotes email-based workflows (though some components have read-only web interfaces, at least) so it doesn’t meet requirement 5.

Unlike all the other options, I feel pretty okay recommending this one because it is actually reasonable to self-host.

Forging a better forge

If I were to go “all in” on building a new, minimal forge for self-hosters, here’s how I’d do it.

…