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.*
Steven Masley
f25b6294b6