builds.sr.ht can be used to automate the deployment of websites, signing of packages, and more, through the use of build secrets. You can upload the secret keys necessary to run your automation on the web, then make these secrets available to CI jobs.

Our example build manifest

Let's say we have a git repo with static HTML files that we'd like to deploy by sending them to our webserver. A simple build manifest might look like this:

image: alpine/edge
packages:
- rsync
sources:
- https://git.sr.ht/~you/example.org
tasks:
- upload: |
    rsync -r example.org/* example.org:/var/www/

This is straightforward enough - but it won't work because the build won't have authorization to log into example.org.

Generating the secrets & preparing our server

This step will naturally be somewhat different depending on your particular server configuration. You should start by creating a deploy user:

useradd -m deploy

Let's also give this user permission to update /var/www:

usermod -aG www-data deploy
chgrp www-data /var/www
chmod g+rwx /var/www

And finally, let's log in as deploy and generate an SSH key:

sudo su deploy
ssh-keygen
# accept the defaults
cat .ssh/id_rsa.pub >> .ssh/authorized_keys
cat .ssh/id_rsa

This will print out the new SSH private key. Copy this to your clipboard for the next step.

Adding your secret to builds.sr.ht

Go to the builds.sr.ht secret management dashboard and select SSH key for secret type, then paste your key into the textbox. Click submit - and your new secret should show up on the right, along with its UUID.

This UUID is used to uniquely identify this secret in build manifets. Copy this UUID for the next step.

Adding secrets to your build manifest

This part is easy. We can simply add a list of secret UUIDs we want to be available in this build.

image: alpine/edge
secrets:
- c262b238-41de-4b43-a2f9-460424dd7896
packages:
- rsync
sources:
- https://git.sr.ht/~you/example.org
tasks:
- upload: |
    rsync -r example.org/* example.org:/var/www/

It's as easy as that! builds.sr.ht will install this SSH key into your build environment when you submit this build manifest. However, it will only work for builds submitted with your user - if someone else copies and pastes this build manifest, the SSH key will not be added to their build VM.

Controlling the use of secrets

The easiest way to control whether or not secrets work in your build is by turning them off via the API: if you set secrets=false in POST /api/jobs, the secrets will not be resolved. This is automatically done in many places where the build manifest could be modified by an untrusted party - for example, dispatch.sr.ht disables secrets when submitting build manifests from GitHub pull requests.

However, some degree of responsibility lies with you for keeping your secrets secure. Avoid writing build manifests that would print your secrets to the logs, particularly if using file secrets. If a secret is every leaked in this manner, you should consider that secret compromised - revoke it and generate a new one.


Want to learn more about builds.sr.ht? Check out all of our builds.sr.ht tutorials.

Other resources:

About this wiki

commit 317a65b12acde1851bcf637602605f9fc8a7d3d6
Author: Drew DeVault <sir@cmpwn.com>
Date:   2019-09-11T22:30:51+00:00

builds.sr.ht/manifest.md: add newline
Clone this wiki
https://git.sr.ht/~sircmpwn/sr.ht-docs (read-only)
git@git.sr.ht:~sircmpwn/sr.ht-docs (read/write)