docs: lead with env vars in admin docs and add configuration reference - #26824
Conversation
Docs previewCheck 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. |
|
/coder-agents-review |
|
Chat: Review posted | View chat Review history
deep-review v0.9.0 | Round 5 | Status: Panel review (3 reviewers) Last posted: Round 4, 28 findings (4 P2, 11 P3, 1 P4, 11 Nit, 1 Note), COMMENT. Review Finding inventoryFindings
Contested and acknowledgedCRF-1 (P3, scripts/configdocgen/main.go:66) - prepareEnv() duplication
CRF-20 (P3, scripts/configdocgen/main.go:330) - Duplicate heading anchors
Round logRound 1Panel. 4 P2, 4 P3, 6 Nit. Reviewed against a78982c..3bdb27b. Round 2Churn guard: PROCEED. 13 addressed, 1 contested. Panel: CRF-1 closed (6/6 accept). 1 P3, 1 P4 new. Reviewed against 8853f55..c3c8fba. Round 3Churn guard: PROCEED. CRF-15 addressed, CRF-16 superseded by rewrite. Panel: 4 P3, 1 Note, 4 Nit new. Reviewed against 8853f55..27c40cc. Round 4Churn guard: PROCEED. 8 addressed, 1 contested (CRF-20). Panel: CRF-20 closed (3/5 accept). 2 P3, 1 Nit new. Reviewed against 8853f55..91da01d. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
Well-scoped PR with a clear goal: give operators a searchable lookup table for Coder server configuration. The generator follows the existing clidocgen/auditdocgen pattern, the Makefile wiring is correct, and the github-auth.md demo conversion reads well (env-var-first, restart inline, CLI-flag equivalence as a closing note). The generated output links back to the CLI reference for detail, so the two pages are complementary, not redundant.
"Boring code gets silence. This pipeline earned most of its silence." (Hisoka)
4 P2, 4 P3, 6 Nit. The P2s are: the generated file is stale and needs make gen before merge (CRF-4), flag-link anchors break for two options with shorthands (CRF-3), the Dangerous section sort order relies on a Unicode coincidence instead of explicit placement (CRF-2), and 10 of 12 comments in the generator are bloat per the project's comment rules (CRF-8). Note that CRF-3 and CRF-4 interact: regenerating without fixing the anchor bug produces fresh output with broken links.
Process note: the PR description claims "Verified no drift: make gen regenerates the page with no diff against current codersdk.DeploymentValues." Running the generator on the PR branch produces a file that differs from the checked-in version (missing CODER_BOUNDARY_LOG_RETENTION, changed Template Builder Registry URL default). CI's freshness check should block merge, but the verification claim is inaccurate. Also, the second commit subject is 78 characters (convention is under 72).
docs/admin/users/github-auth.md:123
Nit [CRF-14] "it's" should be "its" (possessive, not contraction) in the YAML comment: comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value. This line was not changed by this PR, but the PR restructured the surrounding section. (Leorio)
🤖
🤖 This review was automatically generated with Coder Agents.
Round 2 readyRebased onto current Round-1 findings:
Local verification: 🤖 Posted by Coder Agents on behalf of @nickvigilante. |
|
/coder-agents-review |
## What `clidocgen` and the new `configdocgen` (#26824) both carried a byte-identical `prepareEnv()` that unsets `CODER_*` and pins `CLIDOCGEN_*` / `TMPDIR` so generated docs don't embed the generating host's home directory. This extracts it to `scripts/docgenenv.Prepare()` and migrates `clidocgen`. ## Why Duplication flagged during review of #26824. `configdocgen` adopts the shared helper in that PR, removing its copy. ## Risk Behavior-preserving: regenerating the CLI reference (`make docs/reference/cli/index.md`) yields no diff, and `make pre-commit` passes (`lint/go`, `lint/ts`, `build`). A focused unit test pins the `Prepare()` contract, and `_test.go` files are excluded from `CLIDOCGEN_INPUTS` so test edits don't mark the generated docs stale. <details> <summary>CI status — blocked by an unrelated <code>main</code> breakage (#24993)</summary> All red checks on this PR are inherited from `main`, not caused by these changes. This PR touches only `Makefile` and `scripts/{clidocgen,docgenenv}`; it does not touch Helm. `main` went red at `d0f68cb9b0` ("feat: add listenerset", #24993, merged ~18:26 UTC). The committed `helm/coder/tests/testdata/listenerset*.golden` files don't match what `helm template` renders, so: - **`gen`** regenerates those goldens, and the unstaged-files check fails. - **`test-go-pg` (ubuntu-latest, pg-17) and `test-go-race-pg`** fail only on `TestRenderChart/{coder,default}/listenerset[_redirect]` (golden mismatch; the test prints "Run with -update to update golden files"). The same `test-go-pg` job passes on macOS and Windows, where the Helm render test is skipped, and `scripts/docgenenv` reports `ok` on the failing runners. Base commit `14a61041d9` was green; `main` is red from `d0f68cb9b0` onward. These checks clear once `main` is fixed and this branch is updated. `fmt`, `lint`, `Storybook`, `check-build`, and `test-e2e` are green. </details> --- 🤖 Opened by Coder Agents on behalf of @nickvigilante. --------- Co-authored-by: Cian Johnston <[email protected]>
There was a problem hiding this comment.
All four round 1 P2 findings are resolved. CRF-4 (stale file) regenerated, CRF-3 (flag anchors) fixed with FlagShorthand-aware anchors, CRF-2 (Dangerous sort) replaced with explicit sectionRank, CRF-8 (comment bloat) trimmed. Each fix verified by the panel.
CRF-1 (prepareEnv duplication): panel unanimously accepts the defense (6/6). The copies have already diverged stylistically (Cut vs SplitN) without diverging in behavior. Two small functions in separate main packages, following existing convention, bounded drift risk caught by make gen. Closing.
"I tried to construct a scenario where this change ships and something breaks." (Pariston)
1 P3, 1 P4 new. Both advisory. The generator is clean, the fixes are complete, and the pipeline works.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
The list rewrite is a substantial improvement over the original table. Nested headings grouped by serpent hierarchy, sentence-case titles with acronym preservation, deprecated options sorted to end with bold markers, and section intros from group descriptions. The sentenceCase/stripGroupPrefix/restoreFeatureNames pipeline handles the heading transforms cleanly. Tests added for the text transformation helpers.
CRF-15 (no tests) addressed with 131 lines of table-driven tests. CRF-16 (comment verbosity) superseded by the rewrite; comment quality is much improved (83% bloat rate in R1 down to ~10%).
"I tried to build a case against this approach and couldn't." (Pariston)
4 P3, 4 Nit new. The P3s: "OpenID Connect" gets lowercased to "OpenID connect" in headings while descriptions correctly say "OpenID Connect" (CRF-19), duplicate heading anchors from stripped group prefixes make deep links unstable (CRF-20), TestEmphasizeDeprecation misses the majority code path (CRF-21), and two locations still say "searchable table" after the format became a list (CRF-17). No P0-P2.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
All R3 findings addressed. R4 coverage at 80.6% with TestRenderPipeline now exercising buildTree and render end to end. 25 of 28 findings resolved across 4 rounds.
CRF-20 (duplicate heading anchors): panel vote 3/5 accept the defense. The page had no per-setting anchors before; these are net-new deep-linkability. Each setting's unique env var is the stable identifier operators search for. The anchor instability is a known rough edge, not a regression. Two dissenters (Hisoka, Mafu-san) note the missing ticket for explicit heading IDs. This needs a human decision: file a ticket for stable heading IDs, or accept the current anchors as sufficient.
"These anchors are net-new surface area, not broken old surface area. The finding frames this as instability, but there was nothing stable before." (Meruem)
2 P3, 1 Nit new. Both P3s are test coverage gaps in TestRenderPipeline (DefaultFn path and Dangerous section ordering). Advisory.
CI note: gen is failing. Verified locally that configdocgen output matches the checked-in file; the failure may be from another gen target or a base-branch drift. Worth rebasing.
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
All 28 findings resolved across 5 rounds. Coverage at 82.3% with TestRenderPipeline exercising the full pipeline (buildTree, sortTree, render, toOption including DefaultFn, sectionRank including Dangerous ordering, deprecated sinking, flag shorthand anchors, nested sections). Two contested findings closed by panel (CRF-1 prepareEnv at 6/6, CRF-20 anchors at 3/5). No open items.
The generator is clean, proportional to the task, and follows the project's existing docgen patterns. The github-auth.md conversion reads well. The style guide codifies the env-var-first convention.
"Boring code gets silence. This pipeline earned most of its silence." (Hisoka, R1)
🤖 This review was automatically generated with Coder Agents.
429ae8f to
d8e0c8f
Compare
Coder server runs as a system service or container in production. Both read configuration from environment variables, but the admin docs lead with `coder server --flag` examples and only mention the env var form as an afterthought. Operators have to translate every flag to its CODER_* name. Three changes, all small and independent: - New generated page docs/admin/setup/configuration-reference.md with a searchable table of every visible deployment option (Setting, Env var, Flag, YAML key, Default, Description). Grouped by serpent group, with the General section first. Generated from codersdk.DeploymentValues so it stays in sync. - docs/admin/users/github-auth.md inverted to lead with the env-var form in /etc/coder.d/coder.env. The CLI flag form becomes a closing note that links to the new configuration reference. H2 slugs preserved. - DOCS_STYLE_GUIDE entry stating the env-var-first convention for admin/setup docs, with the CLI flag form reserved for ad-hoc invocations. Plumbing: new scripts/configdocgen binary, Makefile target, and GEN_FILES entry. docs/manifest.json wires the new page under Administration / Setup. docs/admin/setup/index.md gains a TIP callout pointing at the reference. Co-authored-by: Coder Agents <[email protected]>
…alues The page committed from the original branch was generated from an older codersdk.DeploymentValues snapshot. Regenerate it so it matches current main: adds CODER_SCIM_USE_LEGACY, the Networking / Cluster section with CODER_CLUSTER_HOST, CODER_BOUNDARY_LOG_RETENTION, and refreshed option descriptions (including the AI Gateway rename). Fixes the gen and check-docs CI failures.
The generator linked every flag to server.md#--<flag>, but clidocgen
anchors short-form flags by their full heading ("### -l, --log-filter"
-> "#-l---log-filter"), so --config and --log-filter pointed at missing
anchors. Derive the anchor from FlagShorthand to match.
Also ignore the AWS Bedrock base URL in linkspector: it appears as an
illustrative https://bedrock-runtime.<region>.amazonaws.com placeholder
in an option description, matching the existing openai.com ignore
patterns.
Resolve the open findings from the coder-agents-review round: - Pin the Dangerous section to last explicitly via sectionRank instead of relying on the emoji sorting after ASCII letters (CRF-2). - Escape pipe characters in the Setting column so an option name cannot break a table row (CRF-5). - Soften the header's universal claim; the table shows "-" where a method does not apply (CRF-6). - Replace the "(dynamic)" default label with "(computed at runtime)" (CRF-7). - Trim comments that restate the code, per the repo comment rules (CRF-8). - Use strings.Cut and slices.Sort* over strings.SplitN and sort.* (CRF-11, CRF-12). - Make _gen/bin/configdocgen a normal Makefile prerequisite to match clidocgen (CRF-13). - Style guide: use sh fences and a real option (CODER_UPDATE_CHECK) in the examples (CRF-9, CRF-10). - github-auth.md: fix "it's" -> "its" (CRF-14). Regenerate the reference against current main; output is idempotent. Co-authored-by: Coder Agents <[email protected]>
Replace the wide table with a nested, per-setting list so the reference fits without horizontal scrolling. Sections now nest by serpent group hierarchy (e.g. Email > Email authentication) and headings use sentence case with the redundant group prefix stripped (e.g. "AI Gateway Send Actor Headers" becomes "Send actor headers"). Deprecated options sort to the end of each section and lead with an emphasized marker, keeping heading anchors stable.
Keep branded feature names (AI Gateway, AI Gateway Proxy, Template Builder) in their canonical casing while sentence case remains the default for all other headings.
Cover sentenceCase, stripGroupPrefix, shortTitle, isDeprecated, emphasizeDeprecation, and collapse (addresses CRF-15).
Address configuration reference review feedback: - Restore "OpenID Connect" casing in generated headings by adding it to the preserved-casing list. - Describe the page as a list, not a table, in index.md and manifest.json. - Add a render-pipeline test and cover the UseInstead deprecation path. - Convert the map-based tests to table-driven subtests for deterministic output. - Rename properNoun to properNouns and trim generator comments.
Rebasing onto main picked up the new --ai-gateway-proxy-target option and a backtick fix in the GitHub allowed-teams help text. Regenerate the page so make gen and check-docs stay clean.
Review feedback noted the demo conversion led with a systemd/coder.env assumption, but a large share of deployments run on Kubernetes. Reframe Step 2 so the environment-variable guidance does not assume a system service: a neutral lead sentence, then Helm values.yaml and /etc/coder.d/coder.env as co-equal paths (Helm first) rather than the system service as default with Helm as an afterthought. Also align the DOCS_STYLE_GUIDE env-var-first convention so it no longer singles out systemd as its only concrete example.
d8e0c8f to
bc9b7ac
Compare
What & why
Admin/setup docs lead with
coder server --flagexamples, but most operators configure Coder throughCODER_*environment variables (system service, container, or Helm chart). There is no single page mapping a setting to its env var, CLI flag, YAML key, and default, so searching the docs for an env var name such asCODER_PG_CONNECTION_URLreturns nothing.This adds a generated configuration reference and begins shifting admin docs to lead with the environment-variable form.
Changes
docs/admin/setup/configuration-reference.md): a searchable, per-setting list of every visible deployment option. Each option is a heading (grouped and nested by serpent group) followed by its description and the environment variable, CLI flag, YAML key, and default that apply to it. Generated fromcodersdk.DeploymentValuesso it stays in sync.make genwiring (scripts/configdocgen/): new binary plus a Makefile target andGEN_FILESentry, mirroring the existingclidocgen/auditdocgenpattern. Output is host-independent (same env normalization asclidocgen).docs/admin/users/github-auth.md): inverted to lead with the/etc/coder.d/coder.envenv-var form; the CLI-flag form becomes a closing note that links to the reference. H2 slugs preserved..claude/docs/DOCS_STYLE_GUIDE.md): documents the env-var-first convention for admin/setup docs.Risk
Docs + gen pipeline only; no runtime change. The page is regenerated by
make gen; thegenandcheck-docsCI checks pass.Follow-up
Several other admin pages still lead with flag walls. Recommend sweeping them incrementally in separate PRs rather than expanding scope here.
Implementation notes (provenance, conflict resolution, verification)
kayla/docs-env-vars-firstbranch. Both original commits are cherry-picked here with authorship preserved.main. Resolved twoMakefileconflicts wheremainhad since added thefeature-stages.mdgen target at the same locations; kept both targets (union) inGEN_FILES,gen/mark-fresh, and the recipe block.codersdk.DeploymentValueschanges, so it was regenerated against currentmain(addsCODER_SCIM_USE_LEGACY, theNetworking / Clustersection withCODER_CLUSTER_HOST,CODER_BOUNDARY_LOG_RETENTION, and the AI Gateway description rename). ThegenCI check enforces this stays current.--config,--log-filter): the generator derives the anchor fromFlagShorthandto matchclidocgen's heading (e.g.#-l---log-filter).linkspectorignores the AWS Bedrock base URL that appears as an illustrative<region>placeholder in an option description, consistent with the existingopenai.comignore patterns.Configuration reference layout (2026-07-08 update)
Reworked the reference from a wide table into a nested, per-setting list so it fits without horizontal scrolling and stops repeating the group name in every heading:
-).Email / Email AuthenticationbecomesEmail(h2) with anEmail authentication(h3) subsection instead of a redundant flat title.URL,TLS,OAuth2,GitHub) plus a small proper-noun allowlist (Coder,Terraform,Honeycomb,Anthropic,Bedrock, ...). Example:AI Gateway Send Actor HeadersbecomesSend actor headers.(deprecated)suffix) so their anchors remain stable.Descriptionwhen the source defines one (e.g. DERP); no hand-maintained prose or links are introduced.All transformations run in pure Go at
make gentime (no AI at generation time). Generation is idempotent, andmarkdownlintandgolangci-lintboth pass.🤖 Opened by Coder Agents on behalf of @nickvigilante. Continues work by @aslilac and @bpmct.