Skip to content

feat(coderd): list workspace secrets on workspace build audit entries - #30459

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

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

Conversation

@Emyrk

@Emyrk Emyrk commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Workspace build audit entries now list the build's secrets: name, env var, file path, and whether the request set the secret or it was carried forward from the previous build. Values are never included. Follows up on this review thread.

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
  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 (this PR)
  • Every workspace build audit entry includes its secrets, including builds that fail and orphaned deletes.
  • The entry lists the build's full set of secrets. Removed secrets show up only by being absent.
  • The three places that write build audit entries now share one helper instead of building the fields by hand.
Implementation details
Decision log

(existing decision log, unchanged)


Created by Coder Agents on behalf of @Emyrk.

@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch 4 times, most recently from 2b233ea to 7cab9f2 Compare October 7, 2026 22:33
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch from d4f1956 to 2a3a2a3 Compare October 7, 2026 22:33
@Emyrk
Emyrk marked this pull request as ready for review October 8, 2026 14:42
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from 7cab9f2 to d1201ff Compare October 8, 2026 15:52
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch 2 times, most recently from 94f3f9c to cf4d7ec Compare October 12, 2026 14:59
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from d1201ff to efb97ae Compare October 12, 2026 14:59

@dylanhuff-at-coder dylanhuff-at-coder left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few comments, one that should be addressed before merging other two are lower priority

// Removed secrets have no row, so they are absent from the set. If the
// secrets cannot be listed, the other fields are still returned with the
// error.
func WorkspaceBuildFields(ctx context.Context, db database.Store, workspace database.Workspace, build database.WorkspaceBuild) (AdditionalFields, error) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A pending build can persist request secrets and then be canceled before a provisioner picks it up. That path finishes without a build audit entry; a later build can copy the secret as carry_forward. The audit trail then has no entry tying the original write to its actor. Could we record the metadata at build creation or cover pending cancellation and reaper termination, with a pending-cancel test? Relates to CRF-13 audit follow-up

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. This is a pre-existing gap: a build whose job is canceled while pending (patchCancelWorkspaceBuild completes the job itself when no worker owns it) or failed by the job reaper gets no build audit entry at all today, with or without secrets. The entry has only ever been written from provisionerd's CompleteJob/FailJob and the orphan-delete shortcut. This PR decorates those existing entries, so there is nothing on the pending-cancel or reaper paths to decorate.

The secret metadata still shows up on the next build's entry as carry_forward; what is missing is the entry tying the original write to its initiator. Fixing that means adding build audit entries on those two paths, which is a behavior change for every build, so we will handle it as a follow-up rather than in this stack.

Generated by Coder Agents on behalf of @Emyrk.

Comment thread coderd/audit/workspacebuild.go Resolved
Comment thread coderd/audit/workspacebuild.go Resolved
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from 6cd2457 to 97c6877 Compare October 15, 2026 14:46
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch from 2b560d3 to 355014e Compare October 15, 2026 15:34
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch 3 times, most recently from 032e9bf to 7950d4b Compare October 15, 2026 16:01
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch 2 times, most recently from 2152494 to e5028c5 Compare October 15, 2026 16:21
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from 7950d4b to 9a1ba25 Compare October 15, 2026 16:21
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from 9a1ba25 to 915d9bf Compare October 15, 2026 17:44
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch from e5028c5 to 53ffbbb Compare October 15, 2026 17:44
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from 915d9bf to a6a7b4f Compare October 15, 2026 18:09
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch from 53ffbbb to 2ec6df6 Compare October 15, 2026 18:09
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from a6a7b4f to bd69be8 Compare October 15, 2026 18:37
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch from 2ec6df6 to 72923e9 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 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 added a commit that referenced this pull request Oct 15, 2026
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](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
5. **#30252 Docs (this PR)**
6. #30388 List a build's secrets
7. #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.*
@Emyrk
Emyrk force-pushed the steven/ws-secrets/cli branch from 72923e9 to 491f240 Compare October 15, 2026 21:32
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from bd69be8 to 1317317 Compare October 15, 2026 21:32
@Emyrk
Emyrk changed the base branch from steven/ws-secrets/cli to graphite-base/30459 October 15, 2026 22:39
Emyrk added a commit that referenced this pull request Oct 15, 2026
`coder secret list` now shows the current workspace build's secrets next to your user secrets, and which user secrets they replace. 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
5. #30252 Docs
6. **#30388 List a build's secrets (this PR)**
7. #30459 Audit a build's secrets

- New `GET /workspacebuilds/{workspacebuild}/secrets` lists a build's secrets (metadata only, never values) and which user secret each one replaces.
- Inside a workspace, `coder secret list` includes the current build's secrets. Outside a workspace, use `--workspace` or `--build-id`.
- The agent now exposes `CODER_WORKSPACE_BUILD_ID`, so the CLI knows which build it is running in.
- The agent manifest and the new endpoint use one shared resolver, so they always agree on which secret wins.
- The user secret API is unchanged.

<details>
<summary>Implementation details</summary>

- The manifest carries `workspace_build_id`; the agent sets it as `CODER_WORKSPACE_BUILD_ID`.
- `coderd/workspacesecrets.Resolve(user, build, policy)` decides which secret is delivered on each env var and file. The manifest no longer relies on entry order.
- `codersdk.WorkspaceSecret` embeds `UserSecret` and adds `workspace_build_id`, `ephemeral`, `cleared_at`, `env_replaces`, and `file_replaces`. Secrets whose values a later build cleared are still listed, with `cleared_at` set.
- CLI columns: `source` and `replaced by` are shown by default only when a build is included; `ephemeral` is opt-in. The CLI makes two requests: user secrets, then build secrets.
- Agents that predate the build ID fall back to `CODER_WORKSPACE_ID` and its latest build.

</details>

<details>
<summary>Decision log</summary>

(existing decision log, unchanged)

</details>

---

*Created by Coder Agents on behalf of @Emyrk.*
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from 1317317 to f473800 Compare October 15, 2026 22:40
@Emyrk
Emyrk force-pushed the graphite-base/30459 branch from 491f240 to 03cba25 Compare October 15, 2026 22:40
@graphite-app
graphite-app Bot changed the base branch from graphite-base/30459 to main October 15, 2026 22:40
@Emyrk
Emyrk force-pushed the steven/ws-secrets/audit branch from f473800 to a73e5ee Compare October 15, 2026 22:41
@Emyrk
Emyrk merged commit 357e81b into main Oct 15, 2026
29 of 30 checks passed
@Emyrk
Emyrk deleted the steven/ws-secrets/audit branch October 15, 2026 23:03
@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