## Summary **Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`). Adds a front-matter `title` to every navigable docs page whose title can be migrated **mechanically**, with no editorial judgment. This is the content step that Phase 1 (renderers prefer front-matter title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware, `DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged and live. **Rendered no-op.** The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it. ## What's in this batch Dry-run on `main` (464 navigable pages) splits into: | category | count | this PR | |----------|-------|---------| | already has front-matter title (Reference, from Phase 2 generators) | 196 | skipped (idempotent) | | **mechanical** — leading body H1 equals the manifest label | 138 | ✅ add front-matter `title`, drop the duplicate H1 | | **no body H1** — renders under the manifest label only | 4 | ✅ add front-matter `title` only | | **mismatch** — body H1 differs from the manifest label | 126 | ⏭️ deferred (needs an editorial decision, see below) | 142 files changed, all under `docs/`. ## Deliberately out of scope: the 126 mismatches Pages where the body H1 is richer than the short sidebar label (e.g. label **Modules** / H1 *Contributing modules*, label **Install** / H1 *Installing Coder*) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (`install/cli.md` and `install/index.md` both carry the H1 *Installing Coder*). These will land in follow-up batches **by nav section** once the policy is set, so each gets real review. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Every added front-matter block parses as YAML and its `title` round-trips to the manifest label (checked programmatically across all 142 files). - Every removed line is a leading `# H1` that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing `<!-- markdownlint-disable -->` comments on the two pages that had them. - `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in Phase 4); `MD025` is not tripped because the duplicate body H1s are removed. ``` $ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main) Linting: 142 file(s) Summary: 0 error(s) ``` Linear: DOCS-484 > This PR was created with AI assistance (Coder Agents).
4.6 KiB
title
| title |
|---|
| Secrets |
Coder is open-minded about how you get your secrets into your workspaces. For more information about how to use secrets and other security tips, visit our guide to security best practices.
Use this guide to configure how templates make secrets available to Coder workspaces. To authenticate workspace provisioners with Coder, see the provisioners documentation. For secret values that developers manage themselves, see User secrets.
Before you begin
Your first attempt to use secrets with Coder should be your local method. You can do everything you can locally and more with your Coder workspace, so whatever workflow and tools you already use to manage secrets may be brought over.
Often, this workflow is simply:
- Give your users their secrets in advance
- Your users write them to a persistent file after they've built their workspace
Template parameters are a dangerous way to accept secrets. We show parameters in cleartext around the product. Assume anyone with view access to a workspace can also see its parameters.
SSH Keys
Coder generates SSH key pairs for each user. This can be used as an
authentication mechanism for git providers or other tools. Within workspaces,
git will attempt to use this key within workspaces via the $GIT_SSH_COMMAND
environment variable.
Users can view their public key in their account settings:
Note
SSH keys are never stored in Coder workspaces, and are fetched only when SSH is invoked. The keys are held in-memory and never written to disk.
User secrets
User secrets are developer-managed values that Coder injects at workspace start. If a user secret targets the same environment variable name or file path as a template-provided variable or file, Coder injects the user secret into that workspace. A secret can be disabled, in which case it is stored but not injected until it is re-enabled. User secret values are covered by Database Encryption when it is enabled. See the User secrets guide.
Dynamic Secrets
Dynamic secrets are attached to the workspace lifecycle and automatically injected into the workspace. With a little bit of up front template work, they make life simpler for both the end user and the security team.
This method is limited to services with Terraform providers, which excludes obscure API providers.
Dynamic secrets can be implemented in your template code like so:
resource "twilio_iam_api_key" "api_key" {
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
friendly_name = "Test API Key"
}
resource "coder_agent" "main" {
# ...
env = {
# Let users access the secret via $TWILIO_API_SECRET
TWILIO_API_SECRET = "${twilio_iam_api_key.api_key.secret}"
}
}
A catch-all variation of this approach is dynamically provisioning a cloud service account (e.g GCP) for each workspace and then making the relevant secrets available via the cloud's secret management system.
Displaying Secrets
While you can inject secrets into the workspace via environment variables, you
can also show them in the Workspace UI with
coder_metadata.
Can be produced with
resource "twilio_iam_api_key" "api_key" {
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
friendly_name = "Test API Key"
}
resource "coder_metadata" "twilio_key" {
resource_id = twilio_iam_api_key.api_key.id
item {
key = "Username"
value = "Administrator"
}
item {
key = "Password"
value = twilio_iam_api_key.api_key.secret
sensitive = true
}
}
Secrets Management
For more advanced secrets management, you can use a secrets management tool to store and retrieve secrets in your workspace. For example, you can use HashiCorp Vault to inject secrets into your workspace.
Refer to our HashiCorp Vault Integration guide for more information on how to integrate HashiCorp Vault with Coder.
