How jobs are submitted
Unlike some other build systems, builds.sr.ht does not let you configure builds
on the website itself. Instead, you write build manifests - YAML files that
tell builds.sr.ht what to do. You can then submit these manifests via the API
and we'll assign a runner and execute your job.
For convenience, there are ways of submitting builds automatically throughout
the sr.ht ecosystem - for example by pushing to repositories on git.sr.ht.
These integrations are discussed below. For details on
submitting jobs via the API, see the API reference.
Build manifests are YAML files that contain a description of your build
environment and steps to run in that environment. A very simple example could
- say-hello: |
- say-world: |
When you submit this build, we'll fire up a virtual machine running an
up-to-date image of Alpine Linux. Then, we'll copy your scripts into the machine
and run them one at a time. More complex build jobs will probably use more
features of the build.yml - here's an example that deploys
- setup: |
- build: |
npm run build:production
- deploy: |
sshopts="ssh -o StrictHostKeyChecking=no"
rsync --rsh="$sshopts" -rP index.html $deploy:/var/www/web.synapse-bt.org/
rsync --rsh="$sshopts" -rP dist $deploy:/var/www/web.synapse-bt.org/
A full reference for build manifests is available.
View the full list of supported build images.
builds.sr.ht can keep track of secrets for you, like SSH keys or PGP keys, and
include them in builds for the purpose of deployment. You can manage your
secrets at the secrets dashboard. Each secret
will only be included in the runtime image if the job was submitted using an
OAuth key which has access to the secrets specified in the build manifest.
Each task's script is given a preamble that looks like this:
The actual shell varies depending on your build image.
the environment variables you specified in your manifest, but feel free to
modify it to communicate state between build steps.
The following environment variables are defined for all builds:
- JOB_ID: The ID assigned to this build job
- JOB_URL: The URL at which the build logs and information can be viewed
with a web browser
Build status badges
If you add tags to your build, or enter search terms, you can use these to
create a build status badge like this (the example being the latest status of
The image URL and a markdown snippet are shown in the sidebar of the search
results page or
tag detail page.
Do you have something that integrates with builds.sr.ht? Submit a patch for this
dispatch.sr.ht offers a variety of integrations with
builds.sr.ht, including support for connecting builds.sr.ht to external services
like GitHub. This should be your first stop when looking for an integration.
git.sr.ht will automatically submit builds for you if you store a manifest in
the repository as
.build.yml. Each time you push, a build with this manifest
will be submitted. If the repo you pushed to is present in the manifest's
sources array, we'll edit it to point to the ref you just pushed. You can also
submit several builds on each push by providing
hg.sr.ht will also automatically submit builds for you. The naming conventions
and other details are the same as the process used by git.sr.ht - described