Add docs about keeping build secrets secret

1 files changed, 32 insertions, 3 deletions

diff --git a/builds.sr.ht/index.md b/builds.sr.ht/index.md
index d43fe60..8378c0a 100644
--- a/builds.sr.ht/index.md
+++ b/builds.sr.ht/index.md
@@ -86,9 +86,38 @@ View the full list of [supported build images](compatibility.md).
 
 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](https://builds.sr.ht/secrets). Each secret
-will only be included in the runtime image if the job was submitted using an
-OAuth key which has access to the secrets specified in the build manifest.
+secrets at the [secrets dashboard](https://builds.sr.ht/secrets).
+
+## Keeping your secrets a secret
+
+If you need to reference a secret in a command line argument or shell variable,
+make sure to run `set +x` first to temporarily disable detailed command logging
+in the build shell. Run `set -x` again once you're done handling secret
+information to re-enable command logging. You also need to be careful that
+secrets are not printed to stdout or stderr by the commands which use them
+— add ` 2>&1 >/dev/null` to the affected commands if you need to hide this
+output.
+
+Whenever you submit a build via the API, you can pass the `secrets` parameter (a
+boolean) to explicitly disable secrets. In this case, they will be discarded and
+the build run without including them (it's up to you to deal with this
+gracefully in your shell scripts, by the way). It is important that you use this
+parameter whenever submitting a build which runs code anyone you don't trust
+could have tampered with. This includes not only the build manifests themselves,
+but any code run as a side-effect, like your Makefile.
+
+This is done for you automatically whenever you submit builds using sr.ht
+features. When building patches from your mailing list, sr.ht will automatically
+disable secrets. The same is true of pull requests from GitHub submitted via
+dispatch.sr.ht.
+
+In any case, if your secret is leaked, you **must** consider it permanently
+compromised, revoke it from any services it provides authentication for, and
+generate new secrets from scratch. All build logs are public, and to encourage
+users to roll over secrets which are compromised, our policy is to refuse to
+redact secrets leaked in this manner. If you require some time to fully address
+the consequences of a secret leak, we may redact them for up to one week —
+[email support](mailto:sir@cmpwn.com) if you require this.
 
 ## Build environment