More fleshing out of builds.sr.ht docs

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