docs: audit all 74 reference pages against implementation code#2138
Merged
docs: audit all 74 reference pages against implementation code#2138
Conversation
Systematically audited every reference documentation page against the actual Go source code, protobuf definitions, and Envoy config builders in pomerium/pomerium to verify config keys, types, defaults, accepted values, and behavioral descriptions. Key fixes: Wrong config keys / env vars (would cause config failures): - metrics.mdx: metrics_basic_authentication -> metrics_basic_auth - metrics.mdx: METRICS_CERTIFICATE_FILE_KEY -> METRICS_CERTIFICATE_KEY_FILE - dns.mdx: default_lookup_family -> dns_lookup_family in examples - set-response-headers.mdx: SET_RESPONSE_HEADERS -> HEADERS Wrong defaults (would mislead users): - runtime-flags.md: grpc_databroker_keepalive false -> true; added 6 missing flags (15 total now match code) - dns.mdx: 4 defaults claimed specific values but code uses nil - set-response-headers.mdx: removed phantom X-Content-Type-Options - timeouts.mdx: idle timeout default 5m -> not set - cookies.mdx: CookieSameSite default Lax -> not set Wrong types: - jwt-claim-headers.mdx: string -> map of string - headers.mdx: 3 type mismatches (remove_request_headers, set_response_headers, rewrite_response_headers) - certificates.mdx: certificates type -> array of objects - policy.mdx: string -> object (PPL rule block) Missing documentation: - access-log-fields.mdx: added client-certificate, cluster-stat-name - authorize-log-fields.mdx: added 5 missing fields - tls.mdx: added missing tls_server_name section - circuit-breaker-thresholds.mdx: added layering explanation Removed fake env vars for per-route settings: - additional-login-redirect-hosts.mdx - enable-google-cloud-serverless-authentication.mdx - tls.mdx: tls_downstream_server_name, tls_upstream_server_name Incorrect descriptions: - cluster-name.mdx: full rewrite (name setting, not cluster name) - show-error-details.mdx: removed incorrect branding claim - address.mdx: HTTP -> HTTPS - databroker.mdx: connection string only required for postgres Also updated reference.json types and descriptions to match. AI disclosure: AI drafted all changes across 10 parallel audit agents. Each agent read code, compared claims, and edited docs. Codex independently verified 20 key findings against the code (19/20 confirmed, 1 partial on pre-existing macOS autocert path gap). Validation: prettier, cspell, yarn build all pass. Human reviewed agent summaries and consolidated reference.json updates.
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
desimone
commented
Mar 27, 2026
| "jsonencode", | ||
| "kubeconfig", | ||
| "metallb", | ||
| "Minisforum", |
Contributor
Author
There was a problem hiding this comment.
some spillover from another guide I'm writing but it's fine
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Systematically audited every reference documentation page (74 total) against the actual Go source code, protobuf definitions, and Envoy config builders in
pomerium/pomeriumto verify config keys, types, defaults, accepted values, and behavioral descriptions.Wrong config keys / env vars (would cause config failures)
metrics.mdx:metrics_basic_authentication->metrics_basic_auth(options.go:216)metrics.mdx:METRICS_CERTIFICATE_FILE_KEY->METRICS_CERTIFICATE_KEY_FILE(options.go:221)dns.mdx:default_lookup_family->dns_lookup_familyin examples (options_dns.go:28)set-response-headers.mdx: env varSET_RESPONSE_HEADERS->HEADERS(options.go:567)Wrong defaults (would mislead users)
runtime-flags.md:grpc_databroker_keepalivedefaultfalse->true(runtime_flags.go:25); added 6 missing flags (15 total now match code)dns.mdx: 4 defaults claimed specific values but code uses nil/Envoy defaultsset-response-headers.mdx: removed phantomX-Content-Type-Options: nosniffdefault headertimeouts.mdx: idle timeout default5m-> not set (Envoy default applies)cookies.mdx: CookieSameSite defaultLax-> not set (browsers default to Lax)Wrong types
jwt-claim-headers.mdx:string->map of string(custom.go:105)headers.mdx: 3 type mismatches fixed (remove_request_headers,set_response_headers,rewrite_response_headers)certificates.mdx:certificatestype corrected to array of objects with cert/keypolicy.mdx:string->object(PPL rule block)Missing documentation
access-log-fields.mdx: added 2 fields (client-certificate,cluster-stat-name)authorize-log-fields.mdx: added 5 fields (including route checksums)tls.mdx: entiretls_server_namesection was missingcircuit-breaker-thresholds.mdx: added global/route/internal cluster layering explanationRemoved fake env vars for per-route settings
additional-login-redirect-hosts.mdx,enable-google-cloud-serverless-authentication.mdx,tls.mdxIncorrect descriptions
cluster-name.mdx: full rewrite -- was "Cluster Name", now accurately describesnamesettingshow-error-details.mdx: removed incorrect branding claimaddress.mdx: "HTTP" -> "HTTPS"databroker.mdx: connection string only required for postgres, not fileTest plan
npx prettier --check-- passednpx cspell-- passed (0 issues)yarn build-- passed (pre-existing broken anchors in unrelated pages only)AI disclosure
AI drafted all changes across 10 parallel audit agents. Each agent read the doc page, the corresponding Go struct/mapstructure tags, default values, and consumption sites, then compared and fixed. Codex independently verified findings against the code. Human reviewed agent summaries, consolidated reference.json updates, and approved the final diff.