Add build secrets doc

3 files changed, 113 insertions, 31 deletions

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).
 
 <div class="alert alert-info">
   <strong>Want to learn more about builds.sr.ht?</strong>
-  Check out all of our <a href="..">builds.sr.ht tutorials</a>.
+  Check out all of our <a href="builds.sr.ht">builds.sr.ht tutorials</a>.
 </div>
 
 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.
     </p>
-    <a href="../getting-started-with-builds.md" class="btn btn-default">
+    <a href="../getting-started-with-builds.md" class="btn btn-success">
       Read more
       <span class="icon icon-caret-right">
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
@@ -35,44 +35,19 @@
     </span>
   </a>
 </div>
-<!--
 <div class="tutorial">
-  <h3>Contributing to projects on sr.ht</h3>
+  <h3>Handling secrets in your build manifests</h3>
   <p>
-    How to configure git to send emails and sending your first patches.
+    You can add secrets like SSH keys to your builds to automate deployments
+    and more.
   </p>
-  <a href="contributing-to-projects.md" class="btn btn-default">
+  <a href="using-build-secrets.md" class="btn btn-default">
     Read more
     <span class="icon icon-caret-right">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
     </span>
   </a>
 </div>
-<div class="tutorial">
-  <h3>Accepting patches from a mailing list</h3>
-  <p>
-    Integrating patches from mailing lists into your own projects.
-  </p>
-  <a href="accepting-patches-from-lists.md" class="btn btn-default">
-    Read more
-    <span class="icon icon-caret-right">
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
-    </span>
-  </a>
-</div>
-<div class="tutorial">
-  <h3>Using secrets on builds.sr.ht</h3>
-  <p>
-    How to securely use secret data in builds.sr.ht jobs.
-  </p>
-  <a href="using-secrets-in-builds.md" class="btn btn-default">
-    Read more
-    <span class="icon icon-caret-right">
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
-    </span>
-  </a>
-</div>
--->
 <hr />
 <div class="alert alert-primary">
   <strong>More tutorials are coming!</strong>
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.
+
+---
+
+<div class="alert alert-info">
+  <strong>Want to learn more about builds.sr.ht?</strong>
+  Check out all of our <a href="builds.sr.ht">builds.sr.ht tutorials</a>.
+</div>
+
+Other resources:
+
+- [builds.sr.ht secrets manual](/builds.sr.ht/#secrets)