From 1f346f2d016c8531f9ed7bf4e7123c49260a7aa3 Mon Sep 17 00:00:00 2001
From: Son Luong Ngoc <sluongng@gmail.com>
Date: Thu, 31 Aug 2023 15:25:50 +0200
Subject: [PATCH] docs: document env-overrides* headers (#4653)

Co-authored-by: Brandon Duffany <brandon@buildbuddy.io>
---
 docs/secrets.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/secrets.md b/docs/secrets.md
index d5344abfa8f..60f85697613 100644
--- a/docs/secrets.md
+++ b/docs/secrets.md
@@ -68,6 +68,64 @@ repository.
 Workflow secrets are accessed via environment variables, in the same way
 as normal Bazel actions shown above.
 
+## Short-lived secrets
+
+For secrets that have a short Time To Live (TTL), BuildBuddy supports setting
+environment variables via special headers passed at the Bazel command line.
+Headers are more secure than setting environment variables with Bazel,
+as they are not stored in the remote cache.
+
+```bash
+# For simple secrets
+--remote_exec_header=x-buildbuddy-platform.env-overrides=VAR_A=value_a,VAR_B=val_b
+
+## At execution time:
+> echo $VAR_A
+value_a
+> echo $VAR_B
+val_b
+
+---
+
+# For more complex secrets
+
+## First encode the secrets using base64,
+## making sure to include the entire 'KEY=VALUE' pair
+> echo -n 'VAR_C={"a": 1, "b", 2}' | base64
+> echo -n 'VAR_D=asdfa!@#C,+{}' | base64
+
+## then use the base64-encoded strings in the `env-overrides-base64` header, comma separated.
+--remote_exec_header=x-buildbuddy-platform.env-overrides-base64=VkFSX0M9eyJhIjogMSwgImIiLCAyfQ==,VkFSX0Q9YXNkZmEhQCNDLCt7fQ==
+
+## At execution time:
+> echo $VAR_C
+{"a": 1, "b", 2}
+> echo $VAR_D
+asdfa!@#C,+{}
+```
+
+:::note
+
+If multiple values are given with the same variable name, the last value will be used.
+If a variable is specified in both `env-overrides` and `env-overrides-base64`,
+`env-overrides-base64` will take priority.
+
+:::
+
+These secrets will be set as environment variables at action execution time,
+overriding the default environment variables on your container image as well as
+the environment variables set by Bazel as part of the action configuration.
+
+:::warning
+
+Secrets may be cached as part of action results if not properly handled.
+Avoid printing secret values to the console or storing them in action outputs.
+
+:::
+
+Secrets that are passed through `env-overrides` or `env-overrides-base64` headers
+are not subjected to `include-secrets` control documented above.
+
 ## Security notes
 
 Secrets are encrypted on the client-side using