aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDrew DeVault <sir@cmpwn.com>2017-12-03 13:02:23 -0500
committerDrew DeVault <sir@cmpwn.com>2017-12-03 13:05:22 -0500
commita00ebba2817031c855e322d26b73a4d5bb812269 (patch)
treebb3a833b5c7409d81c3d89cea88ada53bcd45cb0
parentbc2c815c5b631e5f09326506b52db8675226f255 (diff)
downloadsr.ht-docs-a00ebba2817031c855e322d26b73a4d5bb812269.tar.gz
More fleshing out of builds.sr.ht docs
-rw-r--r--builds.sr.ht/index.md96
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`.