From fe4a73f8ab1b784e8af6f197c20122d7993270bc Mon Sep 17 00:00:00 2001 From: dylanhuff-at-coder Date: Mon, 3 Aug 2026 16:06:30 -0400 Subject: [PATCH] docs: note user secret target uniqueness and delivery boundary (#27532) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two gaps in the user secrets guide, both independent of any pending secrets work. ## Changes **Target uniqueness (`Update a secret`, `File secrets`).** The guide teaches `coder secret update api-key --file ""` but never states that env names and file paths are unique per user, so the conflict you get when setting a target back has no explanation in the docs. The `File secrets` paragraph also read as though duplicate file paths are tolerated with a warning; an identical path is rejected outright, while two *different* paths resolving to the same location are both accepted and produce the agent warning. Both indexes are partial (`WHERE env_name != ''` / `WHERE file_path != ''`), so a cleared target really is released for another secret to claim — now stated. **Delivery boundary (`How your secrets reach a workspace`).** Coder controls where a secret is delivered, not whether it is still valid. Nothing done in Coder revokes a credential a workspace already received, so an exposed credential is rotated at its source. This applies to deletion as much as to clearing a target. No new headings, no changes to the existing tables or callouts. > This PR was generated by Coder Agents on behalf of @dylanhuff-at-coder. --------- Co-authored-by: Nick Vigilante --- docs/user-guides/user-secrets.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/user-guides/user-secrets.md b/docs/user-guides/user-secrets.md index ff2c862854..df9494f666 100644 --- a/docs/user-guides/user-secrets.md +++ b/docs/user-guides/user-secrets.md @@ -55,6 +55,10 @@ injected until the agent manifest is refetched, which happens on workspace restart. Disabling does not remove a file that was already written; the same "Coder never deletes secret files" rule below applies. +Coder controls where a secret is delivered, not whether it is still valid. +Changing or deleting a secret in Coder does not revoke a credential that a workspace has already received. +If a credential is exposed, rotate or revoke it in the system that issued it. + ### Environment variable secrets Coder injects environment variable secrets into every new shell, terminal, @@ -95,9 +99,10 @@ the existing permissions alone. > a terminal in your workspace and run `rm `. Rebuilding the workspace > may clear stale files when your template recreates the filesystem. -If you set two file secrets that resolve to the same absolute path (for -example `~/config` and `/home/coder/config`), only one of them ends up on -disk; the workspace agent logs a warning to help spot this. Use +Coder rejects a second secret that uses a file path you already use. Two +different paths can still resolve to the same absolute path (for example +`~/config` and `/home/coder/config`). Coder accepts both, but only one of them +ends up on disk; the workspace agent logs a warning to help spot this. Use distinct paths to avoid the collision. ## Limits @@ -263,6 +268,12 @@ coder secret update api-key --env NEW_API_KEY coder secret update api-key --file "" ``` +Environment variable names and file paths are unique among your own secrets. +Coder rejects an update that uses an environment variable name or file path that another of your secrets already uses. + +Clearing a target frees it for your other secrets to use. +If another secret takes it, setting the original target back is rejected until you free it again. + ### Enable and disable a secret Disable a secret to stop injecting it without deleting it, then enable it again