Jon Eskin's Website

Self Hosting Git Repositories with Stagit

Note: this post is a work in progress. Feedback to my public inbox is welcome.

Introduction

An alternative to using forges like Github to host your source repositories is to host them your own server. This commonly involves running git as a daemon on a server and deploying a web interface such as gitea, gitlab, cgit, or sourcehut. These projects essentially serve web applications that interface with the git server.

However, if you’re not hosting large, established projects with frequent contributors, these options are probably overkill. Another option I came across recently is stagit. Unlike the aforementioned projects, stagit does not serve dynamic web content; it’s a static site generator that traverses git repositories using libgit2. In addition to being easier to setup and maintain, this approach limits your server’s attack surface.

I set up Stagit on the VPS that I host this blog from; you can see it’s output by navigating to the Git link in the nav header on this page. It was a very smooth process and I’m happy with the result, so I thought I’d write up a quick post about the project.

Stagit

Stagit consists of two commands: stagit-index,which produces an index page that points to all your repositories, and stagit, which builds HTML pages for a single repository.

Using them works as follows: you first run stagit-index passing in all of your git repositories as command line arguments, and then run stagit separately for each individual repository. There’s a shell script in the stagit repo that will do both of these for you.

This will create the HTML pages that describe the current state of all repositories, but it won’t update them for you when the repositories change. For this, you use git’s server-side post-receive hook to update HTML pages for the index and the repository receiving the commit. Stagit provides another sample script that you can tweak and use for this as well.

Here’s how the index page looks out of the box (stagit’s author’s page is shown):

stagit-index

And here’s what you see when you click on a repository:

stagit-repo

Impressions

Stagit shows exactly what I’m interested in when I’m viewing git repositories in a browser without clutter.

Overall I find signal to noise ratio to be very high. In contrast, many forges bombard visitors with a ton of information and are difficult to read at first glance. Some make it difficult to find what you’re looking for even when you use them semi-frequently.

I dug through the codebase out of curiousity to see if I could make a few opinionated tweaks on my setup. The source code is very clear and readable, and I was able to understand and modify it even though I’m not much of a C programmer.

I added in markdown rendering for READMEs, syntax highlighting on files, and made repositories default to the README when it’s available rather than the log page. I also tweaked the provided light and dark themes to match my blog. If you’re curious, you can take a look at my fork here. When I get a chance, I’m planning to add an option to view raw files and maybe make the interface a little more responsive.

I would easily recommend giving Stagit a try if you’re interested. You may want to read through the documentation’s list of pros and cons to make sure its the right fit for you.

Lastly, if you have questions or get stuck trying to set up a git server or Stagit, drop an email in my public inbox. I’m happy to give pointers or do a quick installation screencast if it would help anybody out.

Until next time!