Repository navigation
docs(docs/admin/security): document workspace secrets - #30252
Merged
Merged
Conversation
This was referenced Oct 1, 2026
Member
Author
Contributor
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. |
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 1, 2026 14:52
39825cd to
742e46b
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 1, 2026 14:52
9d02e22 to
8af4ba2
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 1, 2026 15:42
8af4ba2 to
afabae6
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 1, 2026 15:42
742e46b to
a5ae223
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 1, 2026 15:54
afabae6 to
e708864
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
2 times, most recently
from
October 2, 2026 14:27
ad99f56 to
8603a98
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
2 times, most recently
from
October 5, 2026 19:43
12dbe95 to
9ec739b
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 5, 2026 19:43
8603a98 to
daf6e9f
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 5, 2026 20:10
9ec739b to
6d5257f
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 5, 2026 20:10
daf6e9f to
86a6ee3
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 5, 2026 21:07
6d5257f to
38c2f85
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 5, 2026 21:07
86a6ee3 to
25dca00
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 6, 2026 01:53
38c2f85 to
ae98426
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
2 times, most recently
from
October 6, 2026 18:20
7a6a88f to
00eef29
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 6, 2026 18:20
ae98426 to
1dd73cd
Compare
Emyrk
marked this pull request as ready for review
October 6, 2026 18:39
Contributor
Documentation CheckUpdates Needed
Automated review via Coder Agents |
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 15, 2026 15:34
826d8ce to
2621815
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 15, 2026 15:34
39deb89 to
8584e18
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
2 times, most recently
from
October 15, 2026 16:01
2621815 to
f41cfc3
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 15, 2026 16:21
5f54fe1 to
5d6663f
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
2 times, most recently
from
October 15, 2026 17:44
5dbeea7 to
ee3584f
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 15, 2026 17:44
5d6663f to
98091ac
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 15, 2026 18:09
ee3584f to
4770bb2
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
2 times, most recently
from
October 15, 2026 18:34
17f3959 to
e2f6b1e
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
2 times, most recently
from
October 15, 2026 18:37
e375d66 to
d850a41
Compare
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
from
October 15, 2026 18:37
e2f6b1e to
93021fe
Compare
Emyrk
added a commit
that referenced
this pull request
Oct 15, 2026
Encrypts workspace secret values at rest with the existing database encryption keys, and adds workspace secrets to the `coder server dbcrypt` commands. Part of [RELAY-7](https://linear.app/codercom/issue/RELAY-7/agent-relay-deliver-provider-credentials-via-coder-secrets-instead-of). **Stack** (design decisions in #30248) 1. #30248 Database schema, queries, and RBAC 2. **#30249 Encryption at rest (this PR)** 3. #30250 Set secrets on workspace builds 4. #30251 Deliver secrets to the agent 5. #30252 Docs 6. #30388 List a build's secrets 7. #30459 Audit a build's secrets - Values are encrypted when a secret is written and decrypted when it is read. - `dbcrypt rotate` and `dbcrypt decrypt` re-encrypt or decrypt workspace secrets, 1,000 at a time. - `dbcrypt delete` clears workspace secret values instead of deleting the rows, so build history is kept. <details> <summary>Implementation details</summary> - `InsertWorkspaceSecret` and `UpdateEncryptedWorkspaceSecretValue` encrypt, and `ListActiveWorkspaceSecrets` and `GetWorkspaceSecrets` decrypt. Only live rows reach these paths, so there is no NULL handling. - Rotate and decrypt page through `GetWorkspaceSecrets` by `id`, so memory is bounded on large deployments. Only live rows are listed, about one set per workspace. - If a build clears a row between the list and the update, the update matches no row and that row is skipped. - Secret size limits count stored ciphertext bytes, the same as user secrets. Fixing that for both is tracked in #30441. </details> --- *Created by Coder Agents on behalf of @Emyrk.*
Emyrk
added a commit
that referenced
this pull request
Oct 15, 2026
Lets clients set secrets when creating a workspace or a build. Secrets are saved with the build and are never sent to the provisioner. Part of [RELAY-7](https://linear.app/codercom/issue/RELAY-7/agent-relay-deliver-provider-credentials-via-coder-secrets-instead-of). **Stack** (design decisions in #30248) 1. #30248 Database schema, queries, and RBAC 2. #30249 Encryption at rest 3. **#30250 Set secrets on workspace builds (this PR)** 4. #30251 Deliver secrets to the agent 5. #30252 Docs 6. #30388 List a build's secrets 7. #30459 Audit a build's secrets - `secrets` is a new field on the create workspace and create build requests. - Each secret is delivered as an env var, a file, or both. `ephemeral` secrets last for one build only. - Secrets carry forward to every later build until a request replaces or removes them. - A secret set on another secret's env var or file path replaces that secret entirely. - A null `value` removes a secret, which needs `update` permission on the owner's workspace secrets. - Deleting a workspace clears its secret values. Secrets are stored but not delivered to the agent until #30251. <details> <summary>Example request</summary> ```json POST /api/v2/workspaces/{workspace}/builds { "transition": "start", "secrets": [ { "name": "openai-key", "value": "sk-...", "env_name": "OPENAI_API_KEY" }, { "name": "kubeconfig", "value": "apiVersion: v1 ...", "file_path": "~/.kube/config" }, { "name": "session-jwt", "value": "eyJ...", "env_name": "SESSION_JWT", "ephemeral": true }, { "name": "old-token", "value": null } ] } ``` </details> <details> <summary>Implementation details</summary> - Validation reuses the user secret field rules and the file path delivery policy. It rejects: - duplicate names, env names, or file paths within one request - a removal that also sets a target or `ephemeral` - In the build transaction, the builder: 1. copies the previous build's live, non-ephemeral secrets that the request does not name or take over 2. inserts the requested secrets 3. "Earlier builds' rows are cleared when the new build's job completes - Copying and clearing run as `AsWorkspaceSecretManager`, so autostart and other system-initiated builds work without secret permissions. Requested secrets are authorized as the build's actor. - Each row records `source` (`request` or `carry_forward`). - Per-build limit violations return a 400. - A completed delete in `provisionerdserver`, or an orphan delete in the builder, clears the workspace's values and keeps the rows. </details> --- *Created by Coder Agents on behalf of @Emyrk.*
Emyrk
force-pushed
the
steven/ws-secrets/manifest
branch
2 times, most recently
from
October 15, 2026 19:21
3230dcb to
6b6630f
Compare
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 15, 2026 19:21
d850a41 to
67f8160
Compare
Emyrk
changed the base branch from
steven/ws-secrets/manifest
to
graphite-base/30252
October 15, 2026 19:38
Emyrk
added a commit
that referenced
this pull request
Oct 15, 2026
Delivers workspace secrets to the agent, so they show up as env vars and files in the workspace. Part of [RELAY-7](https://linear.app/codercom/issue/RELAY-7/agent-relay-deliver-provider-credentials-via-coder-secrets-instead-of). **Stack** (design decisions in #30248) 1. #30248 Database schema, queries, and RBAC 2. #30249 Encryption at rest 3. #30250 Set secrets on workspace builds 4. **#30251 Deliver secrets to the agent (this PR)** 5. #30252 Docs 6. #30388 List a build's secrets 7. #30459 Audit a build's secrets - The agent receives the secrets of the build that created it, alongside the owner's user secrets. - A workspace secret wins over a user secret on the same env var or file path. - An agent from an older build gets no workspace secrets. - The agent itself needs no changes. <details> <summary>Implementation details</summary> - `GetManifest` finds the agent's build through its resource and provisioner job, then lists that build's live secrets as `AsWorkspaceSecretManager`. - In this PR, precedence comes from order: user secrets are emitted first and workspace secrets after, so the agent applies the workspace value last. #30388 replaces this with `workspacesecrets.Resolve`, which decides one winner per target and is shared with the build secrets API. - The deployment's file path policy applies to both kinds of secret. When file delivery is blocked, a file-only secret is dropped. </details> --- *Created by Coder Agents on behalf of @Emyrk.*
auto-gen api docs do exist
Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
Emyrk
force-pushed
the
steven/ws-secrets/docs
branch
from
October 15, 2026 19:39
67f8160 to
77b0b70
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Adds a short "Workspace secrets" section to the secrets security page, explaining what workspace secrets are and how they differ from template parameters. Part of RELAY-7.
Stack (design decisions in #30248)
The section is intentionally brief. The API reference covers the request fields.
Created by Coder Agents on behalf of @Emyrk.