Add manifest reference under builds.sr.ht

1 files changed, 103 insertions, 0 deletions

diff --git a/builds.sr.ht/manifest.md b/builds.sr.ht/manifest.md
new file mode 100644
index 0000000..95510cd
--- /dev/null
+++ b/builds.sr.ht/manifest.md
@@ -0,0 +1,103 @@
+A build manifest is a YAML file that describes how to perform a build. Here's an
+example:
+
+    image: archlinux
+    packages:
+      - cmake
+      - wlc-git
+      - xorg-server-xwayland
+      - xcb-util-image
+      - json-c
+      - pango
+      - cairo
+      - wayland
+      - gdk-pixbuf2
+      - asciidoc
+    sources:
+      - https://github.com/SirCmpwn/sway
+    tasks:
+      - setup: |
+          cd sway
+          mkdir build
+          cd build
+          cmake ..
+      - build: |
+          cd sway
+          cd build
+          make
+
+The minimum build manifest has an image and at least one task. The various
+properties available are described here:
+
+## image
+
+*string*
+
+Which OS image to build in. A list of available build images can be found
+[here](/builds.sr.ht/#build-images).
+
+## packages
+
+*list* (of *string*)
+
+A list of package names to install on the image. The details of this process
+varies from image to image.
+
+## repositories
+
+*dictionary* (of *string: string*)
+
+A list of extra repositories to enable with the image's package manager.
+The format is name: url, and the syntax of url varies between images.
+
+- **Arch Linux** uses `url#key-id`, where `url` is the URL of the package
+repository and `key-id` is the ID of the published PGP key the packages are
+signed with.
+
+## sources
+
+*list* (of *string*)
+
+A list of git repositories to clone into the home directory of the build
+user in the build environment.
+
+## tasks
+
+*list* (of *string*)
+
+A list of scripts to execute in the build environment. These scripts are run
+with the following preamble:
+
+    #!/usr/bin/env bash
+    . ~/.buildenv
+    set -x
+    set -e
+
+~/.buildenv contains environment variables specified by the `environment`
+directive.
+
+Task names must use only lowercase alphanumeric characters or underscores
+and must be <=128 characters in length. Tasks are executed in the order
+specified.
+
+## triggers
+
+*list* (of *trigger*)
+
+A list of triggers to execute post-build, which can be used to send emails
+or do other post-build tasks. This uses the same structure as triggers in
+[the API](/builds.sr.ht/api.md#post-apijobs), but as YAML rather than JSON.
+
+## environment
+
+*dictionary* (of *string: string* OR *string: list*)
+
+A list of key/value pairs for options to set in the build environment via
+~/.buildenv.
+
+## secrets
+
+*list* (of *string*)
+
+List of secret UUIDs to be added to the guest during the build. See also:
+[secrets](/builds.sr.ht#secrets).