This is an adaptation of our [getting started with builds.sr.ht](../getting-started with builds.sr.ht) tutorial, but for code hosted on GitHub.
Unlike platforms like Jenkins, builds.sr.ht does not allow you to pre-configure jobs. And unlike platforms like Travis, jobs are not inherently tied to a git repository. Each job on builds.sr.ht is described ad-hoc with a build manifest, which can be submitted to builds.sr.ht for processing.
Let's start with a basic manifest:
image: alpine/edge tasks: - example: | echo "hello world"
This is a build manifest, written in YAML. When we submit this to builds.sr.ht, it will boot up an Alpine Linux virtual machine using the edge release of Alpine Linux. Then it will execute each of our build tasks - in this case, saying "hello world".
builds.sr.ht has a web submission form, where you can paste a build manifest and submit the job without any additional configuration. This is a useful way of testing build manifests before giving them a permanent home, or running one-off tasks. Visit the job submission form and paste in the example manifest. Add a note, perhaps "my first job", and click "submit" to run the job.
You'll be redirected to the job detail page. In a moment, one of our job runners will pick up the task and start processing it. Within a few seconds, you should see "hello world" shown under the "example" task.
image: alpine/edge packages: - meson sources: - https://github.com/emersion/mrsh tasks: - configure: | cd mrsh meson build - build: | cd mrsh ninja -C build - test: | cd mrsh ninja -C build test
Before starting your tasks, builds.sr.ht will clone each repository listed in
"sources" to the build environment. You can have as many or as few (including
zero) git repositories as you like. builds.sr.ht will also install Alpine
Linux's meson package before starting your build. This uses Alpine's
apk package manager - other images use different package managers.
Portability is important - so let's try running the same manifest on another operating system.
image: freebsd packages: - meson sources: - https://github.com/emersion/mrsh tasks: - configure: | cd mrsh meson build - build: | cd mrsh ninja -C build - test: | cd mrsh ninja -C build test
This one happens to work without any changes, but note that some images have different names for packages, different distributions of coreutils, and so on.
Try making a new "mrsh" repository on your GitHub account. Note that forks won't
work - so make sure you make a new repository and push the mrsh code to it.
Take a look at the
.builds directory in mrsh: each of these build manifests
can be submitted on push or pull request by rigging up a dispatch.sr.ht task.
Go to dispatch.sr.ht and "Configure new task". Pick "GitHub commits > builds.sr.ht jobs" and click "Add task" for your new mrsh repository. That's all you have to do! Now let's make a dummy commit and push it to GitHub to test it out:
git commit --allow-empty -m "Testing builds.sr.ht" git push
Head over to your builds.sr.ht dashboard and you should see your build begin momentarily!
If you want to run your CI against pull requests on GitHub, follow a similar procedure, but select "GitHub pull requests > builds.sr.ht jobs" instead. Then, each new pull request that comes into your repo will be built on builds.sr.ht and the pull request status updated with the build results.
There are a couple of limitations:
If neither of these are the issue, write us an email.