This is an adaptation of our getting started with builds.sr.ht tutorial, but for code hosted on GitHub.

Build manifests

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

Submitting jobs on the web

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.

Adding git repositories to builds

Let's try building mrsh, which depends on meson. Here's a build manifest for it:

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 native apk package manager — other images use different package managers.

Testing on other platforms

Portability is important — so let's try running the same manifest on another operating system.

image: freebsd/latest
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.

Adding these builds to your GitHub repository

Since 2022-10-01, dispatch.sr.ht is now deprecated.

See hottub for third-party integration.


Want to learn more about builds.sr.ht? Check out all of our builds.sr.ht tutorials.

Other resources:

About this wiki

commit 3f05846d481ab9c50df85ab9cd5c830f9f695b7c
Author: Drew DeVault <sir@cmpwn.com>
Date:   2025-01-24T10:44:31+01:00

graphql: document api-meta.json webhook key
Clone this wiki
https://git.sr.ht/~sircmpwn/sr.ht-docs (read-only)
git@git.sr.ht:~sircmpwn/sr.ht-docs (read/write)