builds.sr.ht is SourceHut's continuous integration (CI) service. Users submit "build manifests" and we boot up a virtual machine to run user-defined tasks in. Integrations with other services, like git.sr.ht, as well as third-party services and custom clients, allow you to utilize builds.sr.ht to test patches, deploy websites, publish packages, and so on.

#Documentation index

• Build manifest reference
• Post-build triggers reference
• Build image support matrix
• Build image maintenance
• API reference
• Installation guide

#Introduction

Builds are not configured on builds.sr.ht itself (build configurations are not stateful). Users write a build manifest -- a YAML file with instructions for builds.sr.ht -- and then these manifests are submitted via the API or ad-hoc on the website, and a worker will be assigned to the resulting job. Various integrations with builds.sr.ht provide different ways of submitting your build manifests, such as by adding a build manifest to your git repository.

The simplest way to submit a build manifest is to type it into builds.sr.ht/submit. Try this one:

image: alpine/latest
tasks:
- hello: |
    echo "Hello world!"

Designing and iterating on your build manifests by submitting them directly to builds.sr.ht on the web is a good way of developing and testing build manifests without littering your git repositories with test commits.

Consult the build manifest reference for more details on what you can add to this YAML file. For a quick-start to add manifests to your source code repositories to add CI to your project, consult the git.sr.ht or hg.sr.ht integration documentation. To test patches sent to your mailing lists, see the project hub integration.

#Build environments

Builds run in a virtual machine with one of the many available build images as a base. These are full virtual machines with relatively broad permissions offered to users -- you can use the appropriate tool (e.g. sudo) to become root, for example, or load kernel modules, etc.

#Shell environment

The following environment variables are defined for all builds:

• JOB_ID: The ID assigned to this build job
• JOB_URL: The URL at which the build logs and information can be viewed with a web browser

The following environment variables are commonly added by integrations:

• BUILD_SUBMITTER: The name of the integration which submitted the job
• BUILD_REASON: The reason the integration submitted the build

Some integrations add other variables; consult the relevant documentation for more details.

#SSH access to build VMs

You can interact directly with your builds by connecting to the runner over SSH. This is helpful for troubleshooting your manifests, or just getting a quick temporary environment to test something in.

When a build fails, the VM stays alive for an extra ten minutes, and you'll be presented with instructions on how to connect to the runner via SSH, e.g.:

$ ssh -t builds@fra02.builds.sr.ht connect 81809
Connected to build job #81809 (failed): https://builds.sr.ht/~sircmpwn/job/81809
Your VM will be terminated 4 hours from now, or when you log out.

build:~$

In addition to connecting to failed builds over SSH, you can add shell: true to your manifest to always enable SSH access. Then, you'll be able to interact with your build as it runs.

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

#Keeping your secrets a secret

Note that all builds run with set -x configured, which causes every command executed to be printed to the build log with environment variables expanded. Best practice is to avoid using secrets via environment variables, however, if you must, ensure that any commands in your task scripts which reference secret environment variables are run only after using set +x to disable command logging.

Take care to avoid printing secrets to the standard output or standard error of your task scripts as well. Commands which would log secrets should be patched not to, or failing that, append >/dev/null 2>&1 to suppress their logs.

When submitting builds via the API, the secrets parameter can be used to disable build secrets entirely. Integrations which run untrusted builds will disable secrets in this manner, such as the project hub integration that disables secrets when building patches sent to a mailing list. If secrets are disabled, the build step which installs them in the virtual machine is skipped; you may need to handle their absence as elegantly as possible in your task script.

When builds are submitted via mailing list integration, secrets are disabled.

If your secret is leaked in a public or unlisted build, you must consider it permanently compromised, revoke it from any services it provides authentication for, and generate new secrets from scratch. SourceHut policy forbids us from redacting secrets leaked in this manner in order to encourage users to take appropriate measures to address compromised secrets.

#Build status badges

If you add tags to your build, or enter search terms, you can use these to create a build status badge like this (the example being the latest status of builds.sr.ht itself):

The image URL and a markdown snippet are shown in the sidebar of the search results page or tag detail page.

#Integrations

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

#git.sr.ht

git.sr.ht will automatically submit builds for you; see details here.

#hg.sr.ht

hg.sr.ht will also automatically submit builds for you. The naming conventions and other details are the same as the process used by git.sr.ht — described here.

#Project hub

The project hub can automatically submit builds to verify patches sent to your development mailing list. See details here.

#hut (CLI client)

The hut CLI client for SourceHut provides convenient and easily scriptable access to the builds.sr.ht build submission process.