From e0470b9ee92edd5c14ab5f9e8fd43505e45d02a0 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Sun, 3 Mar 2019 15:14:14 -0700 Subject: Add build secrets doc --- tutorials/builds.sr.ht/github-integration.md | 2 +- tutorials/builds.sr.ht/index.html | 35 ++------- tutorials/builds.sr.ht/using-build-secrets.md | 107 ++++++++++++++++++++++++++ 3 files changed, 113 insertions(+), 31 deletions(-) create mode 100644 tutorials/builds.sr.ht/using-build-secrets.md diff --git a/tutorials/builds.sr.ht/github-integration.md b/tutorials/builds.sr.ht/github-integration.md index 21f9ea7..696eeb3 100644 --- a/tutorials/builds.sr.ht/github-integration.md +++ b/tutorials/builds.sr.ht/github-integration.md @@ -135,7 +135,7 @@ If neither of these are the issue, [write us an email](mailto:sir@cmpwn.com).
Want to learn more about builds.sr.ht? - Check out all of our builds.sr.ht tutorials. + Check out all of our builds.sr.ht tutorials.
Other resources: diff --git a/tutorials/builds.sr.ht/index.html b/tutorials/builds.sr.ht/index.html index 38b952f..3661341 100644 --- a/tutorials/builds.sr.ht/index.html +++ b/tutorials/builds.sr.ht/index.html @@ -14,7 +14,7 @@ Running your first few jobs on our continuous integration platform, builds.sr.ht.

- + Read more @@ -35,44 +35,19 @@ -
More tutorials are coming! diff --git a/tutorials/builds.sr.ht/using-build-secrets.md b/tutorials/builds.sr.ht/using-build-secrets.md new file mode 100644 index 0000000..34a178f --- /dev/null +++ b/tutorials/builds.sr.ht/using-build-secrets.md @@ -0,0 +1,107 @@ +# Handling secrets in your build manifests + +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: + +```yml +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](https://builds.sr.ht/secrets) 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. + +```yml +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](/builds.sr.ht/api.md#post-apijobs), 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: + +- [builds.sr.ht secrets manual](/builds.sr.ht/#secrets) -- cgit