1. Introduction §

If you ever required continuous integration pipelines to do some actions in an OpenBSD environment, you certainly figured that most Git "forge" didn't provide OpenBSD as a host environment for the CI.

It turns out that sourcehut is offering many environments, and OpenBSD is one among them, but you can also find Guix, NixOS, NetBSD, FreeBSD or even 9front!

Let's see how this works.

sourcehut official website

sourcehut: Documentation about host systems offering in CI

Note that the CI is only available to paid accounts, the minimal fee is "$2/month or $20/year". There are no tiers, so as long as you pay something you have a paid account. sourcehut is offering a clutter-free web interface, and developing an open source product that is also capable of running OpenBSD in a CI environment, I decided to support them (I really rarely subscribe to any kind of services).

PS: sourcehut supports Mercurial projects too.

2. The CI §

Upon each CI trigger, a new VM is created, it's possible to define the operating system and version you want for the environment, and then what to do in it.

The CI works when you have a "manifest" file in your project with the path .build.yml at the root of your project, it contains all the information about what to do.

sourcehut: Documentation about manifests and builds

3. Secret management §

When you run code in a CI, you often need secrets, and most often you require SSH keys if you want to push artefacts.

The SSH key secret is simplified, if sourcehut recognizes a secret to be a private SSH key, it will automatically save it at the right place.

sourcehut: Documentation about secrets in CI

4. Example §

Here is a simple example of a manifest file I use to build a website using the static generator hugo, and then push the result on a remote server.

image: openbsd/latest
packages:
  - hugo--
  - rsync--
secrets:
  - f20c67ec-64c2-46a2-a308-6ad929c5d2e7
sources:
  - git@git.sr.ht:~solene/my-project
tasks:
  - init: |
      cd my-project
      git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
  - build: |
      cd my-project
      echo 'web.perso.pw ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKRj0NK7ZPMQgkgqw8V4JUcoT4GP6CIS2kjutB6xdR1P' | tee -a ~/.ssh/known_hosts
      make

On the example above, we can notice different parts:

• image: this tells the manifest which OS to use, openbsd/latest means latest release.
• packages: this tells which packages to install, it's OS-agnostic. I use extra dashes because some alternate versions of these packages exists, I just want the simple flavour for each.
• secrets: this tells which secret I want among the secrets stored in sourcehut. This is a dedicated private SSH key in this case.
• sources: this tells which sources to clone in the CI. Be careful though, if a repository is private, the CI needs to have the SSH key to access the repository. I spent some time figuring this the hard way.
• tasks: this defines which commands to run, they are grouped in jobs.

If you use SSH, don't forget to either use ssh-keyscan to generate the content for ~/.ssh/known_hosts, or add the known fingerprint like me that would require an update if the SSH host key changes.

A cool thing is when your CI job failed, the environment will continue to live for at least 10 minutes while offering an SSH access for debug purpose.

sourcehut: Documentation about SSH into build environments

5. Conclusion §

I finally found a Git forge that is ethic and supportive of niche operating system. Its interface may be rude with fewer features, but it loads faster and is cleaner to understand. The price ($20/year) is higher than the competition (GitHub or GitLab) which can be used freely (up to some point) but they don't offer the CI choice and the elegant workflow sourcehut has.

6. Going further §

You can self-host a sourcehut instance if you prefer, it's open source and packaged for some Linux distributions.

sourcehut: Documentation about the deployment process