builds.sr.ht

builds.sr.ht is a service on sr.ht that allows you to submit "build manifests" for us to work on. We spin up a virtual machine per your specifications and run your scripts in it. This is generally used to compile and test patches, deploy websites, build and publish packages, and so on.

See also:

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

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 be:

image: alpine
steps:
  say hello: |
      echo hello
  say world: |
      echo 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 web.synapse-bt.org:

image: archlinux
packages:
  - nodejs
  - npm
  - rsync
sources:
  - https://git.sr.ht/~sircmpwn/receptor
environment:
  deploy: synapse@synapse-bt.org
secrets:
  - 7ebab768-e5e4-4c9d-ba57-ec41a72c5665
tasks:
  - setup: |
      cd receptor
      npm install
  - build: |
      cd receptor
      npm run build:production
  - deploy: |
      cd receptor
      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.

Build images

Presently, the following build images are available:

  • archlinux
  • debian/buster
  • debian/jessie
  • debian/sid
  • debian/stretch

Additional images are possible - and not just of Linux distros. Please email me if you'd like to see another image.

Secrets

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.

Build environment

Each task's script is given a preamble that looks like this:

#!/usr/bin/env bash
. ~/.buildenv
set -x
set -e

The actual shell varies depending on your build image. ~/.buildenv contains the environment variables you specified in your manifest, but feel free to modify it to communicate state between build steps.

Integrations

Do you have something that integrates with builds.sr.ht? Submit a patch for this page!

git.sr.ht

git.sr.ht can submit builds for you if you store your 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 .builds/*.yml.

Table of Contents

This commit

commit 8cc980855552f02959da7a2c3742e7c68e917538
Author: Drew DeVault <sir@cmpwn.com>
Date:   2018-07-14T22:09:09

Fix some typos in send-email.md
Clone this wiki
man@man.sr.ht:root
https://man.sr.ht/root