Skip to content

docs(docs/admin/security): document workspace secrets - #30252

Merged
Emyrk merged 3 commits into
mainfrom
steven/ws-secrets/docs
Oct 15, 2026
Merged

Emyrk merged 3 commits into
mainfrom
steven/ws-secrets/docs

Conversation

@Emyrk

@Emyrk Emyrk commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

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)

  1. feat: add workspace secrets table, queries, and RBAC #30248 Database schema, queries, and RBAC
  2. feat(enterprise/dbcrypt): encrypt workspace secrets #30249 Encryption at rest
  3. feat: set workspace secrets on workspace builds #30250 Set secrets on workspace builds
  4. feat: deliver workspace secrets in the agent manifest #30251 Deliver secrets to the agent
  5. docs(docs/admin/security): document workspace secrets #30252 Docs (this PR)
  6. feat: list a workspace build's secrets in coder secret list #30388 List a build's secrets
  7. feat(coderd): list workspace secrets on workspace build audit entries #30459 Audit a build's secrets
  • Workspace secrets are set on the create workspace or create build request.
  • They never reach the provisioner, so they stay out of build parameters, Terraform state, insights, and metrics.
  • The agent delivers them the same way as user secrets, and they can't be read back through the API.

The section is intentionally brief. The API reference covers the request fields.


Created by Coder Agents on behalf of @Emyrk.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check 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.

@linear-code

linear-code Bot commented Oct 1, 2026

Copy link
Copy Markdown

RELAY-7

@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 39825cd to 742e46b Compare October 1, 2026 14:52
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 9d02e22 to 8af4ba2 Compare October 1, 2026 14:52
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 8af4ba2 to afabae6 Compare October 1, 2026 15:42
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 742e46b to a5ae223 Compare October 1, 2026 15:42
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from afabae6 to e708864 Compare October 1, 2026 15:54
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch 2 times, most recently from ad99f56 to 8603a98 Compare October 2, 2026 14:27
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch 2 times, most recently from 12dbe95 to 9ec739b Compare October 5, 2026 19:43
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 8603a98 to daf6e9f Compare October 5, 2026 19:43
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 9ec739b to 6d5257f Compare October 5, 2026 20:10
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from daf6e9f to 86a6ee3 Compare October 5, 2026 20:10
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 6d5257f to 38c2f85 Compare October 5, 2026 21:07
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 86a6ee3 to 25dca00 Compare October 5, 2026 21:07
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 38c2f85 to ae98426 Compare October 6, 2026 01:53
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch 2 times, most recently from 7a6a88f to 00eef29 Compare October 6, 2026 18:20
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from ae98426 to 1dd73cd Compare October 6, 2026 18:20
@Emyrk
Emyrk marked this pull request as ready for review October 6, 2026 18:39
@coderagents

coderagents Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Documentation Check

Updates Needed

  • docs/admin/security/secrets.md (open) - The new "Workspace secrets" section omits the per-build limits the API enforces (50 secrets per build, 200 KiB combined value bytes, 24 KiB combined env-injected value bytes, each rejected with a 400 when exceeded). Add a Limits subsection in the pattern of the User secrets guide. The section should also state that a workspace secret overrides a user secret that targets the same environment variable.

Re-reviewed after the 33ed5936 trim. The referenced auto-generated API docs cover the secrets request schema but do not state these enforced caps or the precedence rule, so the gap stands.


Automated review via Coder Agents

@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 826d8ce to 2621815 Compare October 15, 2026 15:34
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 39deb89 to 8584e18 Compare October 15, 2026 15:34
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch 2 times, most recently from 2621815 to f41cfc3 Compare October 15, 2026 16:01
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 5f54fe1 to 5d6663f Compare October 15, 2026 16:21
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch 2 times, most recently from 5dbeea7 to ee3584f Compare October 15, 2026 17:44
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from 5d6663f to 98091ac Compare October 15, 2026 17:44
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from ee3584f to 4770bb2 Compare October 15, 2026 18:09
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch 2 times, most recently from 17f3959 to e2f6b1e Compare October 15, 2026 18:34
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch 2 times, most recently from e375d66 to d850a41 Compare October 15, 2026 18:37
@Emyrk
Emyrk force-pushed the steven/ws-secrets/manifest branch from e2f6b1e to 93021fe Compare October 15, 2026 18:37
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
Emyrk force-pushed the steven/ws-secrets/manifest branch 2 times, most recently from 3230dcb to 6b6630f Compare October 15, 2026 19:21
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from d850a41 to 67f8160 Compare October 15, 2026 19:21

Emyrk commented Oct 15, 2026 •

Copy link
Copy Markdown
Member Author

Merge activity

  • Oct 15, 7:38 PM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Oct 15, 7:40 PM UTC: Graphite rebased this pull request as part of a merge.
  • Oct 15, 7:45 PM UTC: @Emyrk merged this pull request with Graphite.

@Emyrk
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.*
@Emyrk
Emyrk changed the base branch from graphite-base/30252 to main October 15, 2026 19:38
Emyrk and others added 3 commits October 15, 2026 19:39
Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
@Emyrk
Emyrk force-pushed the steven/ws-secrets/docs branch from 67f8160 to 77b0b70 Compare October 15, 2026 19:39
@Emyrk
Emyrk merged commit fa926fc into main Oct 15, 2026
30 of 31 checks passed
@Emyrk
Emyrk deleted the steven/ws-secrets/docs branch October 15, 2026 19:45
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 15, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants