Skip to content

feat: add workspace secrets table, queries, and RBAC - #30248

Merged
Emyrk merged 1 commit into
mainfrom
steven/ws-secrets/db
Oct 15, 2026
Merged

Emyrk merged 1 commit into
mainfrom
steven/ws-secrets/db

Conversation

@Emyrk

@Emyrk Emyrk commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

Adds the database table, queries, and permissions for workspace secrets: secrets set on a workspace build and delivered to the agent, never to Terraform. First PR in the stack for RELAY-7. Supersedes #30200.

Stack

  1. feat: add workspace secrets table, queries, and RBAC #30248 Database schema, queries, and RBAC (this PR)
  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
  • Each secret belongs to one workspace build. A new build copies the previous build's secrets, then the old copies lose their values but stay as history.
  • A new workspace_secret RBAC resource. Owners, org admins, and members with workspace access can set, view, and clear secrets, but nobody can read values through the API.
  • Only a dedicated internal actor, used for agent delivery and carrying secrets forward, can read secret values.
  • Each build is capped like user secrets: 50 secrets, 200 KiB total, 24 KiB in env vars.

Nothing calls these queries yet.

Implementation details
  • Migration 000614_workspace_secrets. Columns mirror user_secrets (value, value_key_id, env_name, file_path), plus ephemeral, cleared_at, and source (request or carry_forward).
  • A check constraint makes each row either live (has a value) or cleared (has cleared_at), never both.
  • A BEFORE INSERT trigger enforces the per-build limits. Like user secrets it counts stored bytes, which are ciphertext when encryption is on (tracked in Secret byte limits measure ciphertext, which breaks near-cap secrets when dbcrypt is enabled #30441).
  • Queries:
    • InsertWorkspaceSecret, ListActiveWorkspaceSecrets
    • ClearWorkspaceSecretsBeforeBuild clears only builds with a lower build number, so a late clear can't wipe a newer build.
    • ClearWorkspaceSecretsByWorkspaceID runs on workspace delete.
    • GetWorkspaceSecretsHistory is metadata only, optionally filtered to one build.
    • GetWorkspaceSecrets (paged by id) and UpdateEncryptedWorkspaceSecretValue are for key rotation.
  • RBAC actions: create, read (metadata), update (clear, remove, re-encrypt), and read_secret. No user role has read_secret, and the general system actor has no workspace secret grants.
  • AsWorkspaceSecretManager holds every workspace_secret action.
  • dbauthz: insert needs create, clear needs update, and history needs read on the workspace owner and org. Any query that returns values needs read_secret.
  • Workspace build API key scopes include workspace_secret:create, and the migration adds the api_key_scope enum values.
Design decisions (whole stack)
Question Decision
Linkage Rows belong to a build. Only the latest build has live rows. Older builds keep cleared rows as history.
Carry-forward Non-ephemeral secrets are copied to each new build unless the request replaces, removes, or takes over their target. A request without secrets still carries the set forward. Copying and clearing run as AsWorkspaceSecretManager, so autostart, the build orchestrator, and prebuilds need no secret permissions.
Copy source The latest build, even if it failed.
Ephemeral Delivered only to the build it was set on, whoever triggers the next build and whether or not it succeeds.
Clearing Superseded rows get value = NULL, value_key_id = NULL, and cleared_at = now(). Metadata is kept.
Write path Inline secrets on the create workspace and create build requests. Setting needs workspace_secret:create on the workspace owner.
Removal "value": null drops the secret and needs workspace_secret:update. An empty string is a real value.
Takeover A requested secret on a previous secret's env_name or file_path supersedes that secret entirely, even if the new one is ephemeral. Needs only create.
Reads Write-only through the API. Values need read_secret, held only by AsWorkspaceSecretManager. History and the build listing are metadata only.
Rotation Skips cleared rows and never writes a value back into one.
Concurrent clears Each build clears only lower build numbers. If two builds race, the later build wins.
Delete A completed or orphan delete clears the workspace's values. Rows are kept as history.
Precedence A workspace secret overrides a user secret on the same env_name or file_path.
Limits The user secret caps, enforced per build.
Source Each row records request or carry_forward, for debugging and the build audit entry.
Audit The workspace build audit entry lists the build's secrets (name, env_name, file_path, source), never values.
Template declaration Nothing is declared in Terraform. A startup script checks for the expected env vars.

Created by Coder Agents on behalf of @Emyrk.

Comment thread coderd/database/dbauthz/dbauthz.go Resolved
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch from 87d458e to e66489e Compare October 1, 2026 14:52
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch 3 times, most recently from 23c9372 to e4c9015 Compare October 2, 2026 14:27
Comment thread coderd/database/dbauthz/dbauthz.go Resolved
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch from e4c9015 to 192d209 Compare October 5, 2026 19:43
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch from a7199ed to 89ea493 Compare October 6, 2026 01:53
@Emyrk
Emyrk marked this pull request as ready for review October 6, 2026 18:13
@Emyrk
Emyrk requested a review from nickvigilante as a code owner October 6, 2026 18:13
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch from e1c97c8 to 8e4631d Compare October 7, 2026 22:33
@Emyrk Emyrk changed the title feat(coderd/database): add workspace_secrets table and queries feat: add workspace secrets table, queries, and RBAC Oct 8, 2026
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch from 8e4631d to 6ddd097 Compare October 8, 2026 15:52
Comment thread coderd/database/querier_test.go Resolved

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

my comments have been addressed, lgtm

Adds the workspace_secrets table with per-build caps, the workspace_secret
RBAC resource and API key scopes, the AsWorkspaceSecretManager actor, and
the queries used by later changes to set, carry forward, clear, list, and
re-encrypt secrets on workspace builds.
@Emyrk
Emyrk force-pushed the steven/ws-secrets/db branch from 9a091b9 to f2c82bf Compare October 15, 2026 17:44
@Emyrk
Emyrk merged commit 7aef110 into main Oct 15, 2026
72 of 74 checks passed
@Emyrk
Emyrk deleted the steven/ws-secrets/db branch October 15, 2026 18:32
@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