Some times ago, a colleague from my network introduced me to SourceHut, an intriguing alternative to mainstream code hosting platforms. Unlike its heavyweight counterparts, SourceHut stands out for its emphasis on lightness and privacy, boasting a fully operational suite of services devoid of any tracking mechanisms, all accessible without the need for JavaScript.

At its core, SourceHut offers version control system (VCS) hosting for both Git and Mercurial, two of the most popular distributed source control management systems. But that’s just the tip of the iceberg. The platform extends its offerings to include issue tracking, a build service, mailing lists, wikis, and a host of other well-documented and intelligently designed tools. It’s an all-in-one solution that instantly piqued my curiosity, compelling me to dive deeper and explore its capabilities firsthand.

Admittedly, the transition wasn’t seamless, primarily due to my long-standing familiarity with GitHub’s workflow. SourceHut aims to harness the inherent functionalities of the underlying tools, such as utilizing Git patches for change sharing, in lieu of proprietary user interfaces or workflows. These patches are dispatched via mailing lists where they are open to discussion and refinement — a practice that harkens back to the roots of open-source collaboration.

With that framework in mind, I embarked on a project to set up a Git repository on SourceHut, with the objective of automating the build process for my static website and deploying it to my web server. The experience, while initially daunting due to my unfamiliarity with Alpine Linux, was surprisingly straightforward.

Setting Up Your Repository

The initial step involves creating an account on SourceHut and subsequently creating a repository. It’s essential to note that build automation is a premium feature, accessible only to paid accounts. However, the barrier to entry is minimal, with a one-month subscription available for as little as $2 — a nominal fee to experiment with the platform’s full potential.

For this demonstration, I’ll use Jekyll, a popular Ruby-based static site generator, to build my blog. While this post will not delve into the specifics of Jekyll, the general workflow outlined should be applicable irrespective of the static site generator employed.

Crafting the Build File

SourceHut simplifies the setup of continuous integration pipelines through the introduction of a .build.yml file to your repository. The structure and syntax of this file dictate the build process, leveraging SourceHut’s curated images without the need for Dockerfiles.

image: alpine/latest
  - rsync
  - ruby-dev
  - ruby-full
  - secret_uuid
  - deploy: |
      cd mywebsite
      [ "$(git rev-parse master)" = "$(git rev-parse HEAD)" ] || complete-build
      sudo gem install bundler
      bundle install
      JEKYLL_ENV=production jekyll build
      rsync -az --no-t --no-p --delete -e "ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no" _site/

Managing Secrets and Branch-specific Actions

A common requirement in the deployment workflow is the use of secrets, such as private keys, for secure file transfer or encryption. Additionally, it’s advisable to conditionally execute certain actions based on the active branch. For instance, you might want to halt the build process prematurely if not on the main branch, using the complete-build command. While this command is not officially documented, acknowledging its existence and potential future changes could save newcomers significant time.


My exploratory journey with SourceHut was both enlightening and fulfilling. The process of automating my website’s deployment was less daunting than anticipated, facilitated by SourceHut’s intuitive build system. While I remain undecided on whether to transition my workflow permanently from GitHub to SourceHut, the experiment underscored the feasibility and efficiency of SourceHut’s tools for various development tasks, from compiling and testing patches to deploying websites and publishing packages.

Have comments or want to discuss this topic?

Send an email to ~bounga/