Title: OpenBSD in a CI environment with sourcehut

	Title: OpenBSD in a CI environment with sourcehut
	Author: Solène
	Date: 03 December 2023
	Tags: openbsd devops git
	Description: In this article, you will learn how to use sourcehut git
	forge to run CI in an OpenBSD environment

	# 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.

	# 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

	# 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

	# 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:
	- [email protected]:~solene/my-project
	tasks:
	- init: \|
	cd my-project
	git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod …
	- build: \|
	cd my-project
	echo 'web.perso.pw ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKRj0NK7ZPMQgkgqw8…
	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

	# 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.

	# 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