diff options
| -rw-r--r-- | builds.sr.ht/index.md | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/builds.sr.ht/index.md b/builds.sr.ht/index.md index 1027492..ef06b5d 100644 --- a/builds.sr.ht/index.md +++ b/builds.sr.ht/index.md @@ -3,3 +3,99 @@ 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. + +# 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](#integrations). For details on +submitting jobs via the API, see the [API reference](api.md). + +## 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](https://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](manifests.md) for build manifests is available. + +## Build images + +Presently, the following build images are available: + +- archlinux +- alpine +- debian/buster +- debian/jessie +- debian/sid + +Additional images are possible - and not just of Linux distros. Please [email +me](mailto:sir@cmpwn.com) if you'd like to see another image. + +## 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`. |