Consolidate environment variable docs into one reference - #4989
Merged
Conversation
The environment variables that configure a Temporal Client were spread across two tables that disagreed with each other and with the code. docs/references/client-envrionment-configuration.mdx listed 16 variables and omitted TEMPORAL_PROFILE. docs/cli/setup-cli.mdx listed 10, and presented TEMPORAL_TLS_CA, TEMPORAL_TLS_CERT, and TEMPORAL_TLS_KEY as current names when the CLI treats them as legacy compatibility shims (cliext/client.go). Neither documented the `temporal env` variables or the remaining legacy TLS names. Consolidate into a single reference covering all 26 variables, with TOML key, CLI flag, and Supported by columns. The Temporal CLI is a Temporal Client, so its variables belong here, marked by scope rather than split onto a separate page. Ten previously undocumented variables are now covered: TEMPORAL_PROFILE, TEMPORAL_CLIENT_AUTHORITY, the two `temporal env` variables, and the six legacy TLS names. Replace the setup-cli.mdx table with a pointer, keeping its #environment-variables anchor and absorbing the shell-variable versus `temporal env` distinction requested in temporalio/cli#776. Add bin/check-env-config-table.js, which extracts variable names from every implementation that reads them (sdk-go, sdk-rust core, sdk-typescript, sdk-java, and the CLI) and fails when the table and the sources disagree. Descriptions stay hand-written; only the variable and support data is checked. Runs weekly rather than per PR because it fetches sources over the network. Fix the misspelled filename. The URL derives from the frontmatter id, so it is unchanged and needs no redirect.
The previous wording said TOML configuration profiles supersede the
`temporal env` preset system and told readers to prefer
TEMPORAL_PROFILE and TEMPORAL_CONFIG_FILE for new setups. The CLI's own
command definitions say otherwise:
temporal config summary: Manage config files (EXPERIMENTAL)
temporal env # TODO(cretz): Deprecate when `config` GA
# deprecated: Use `config` subcommands instead.
The deprecation is commented out pending `config` reaching GA, so
`temporal env` is current and the mechanism being recommended over it is
the experimental one. Describe both as working, and note which is
experimental, rather than ranking them.
That wording came from the design document in temporalio/proposals, which
states the deprecation as though it had happened. Record in the checker
that the proposal describes intent and the implementations are the
authority, so it is not cited that way again.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
Duncanma
approved these changes
Jul 29, 2026
The four-column tables scrolled horizontally, hiding the descriptions. Client settings now use a two-column table with the TOML key and CLI flag folded into each description. The three variables that not every client reads move to their own section, one heading each, with TOML key, CLI flag, and a "Read by:" line. Set toc_max_heading_level: 2 so the per-variable headings give each variable an anchor without filling the table of contents. The checker no longer parses a per-client column, so it derives support from the page structure instead: a table row takes its section's support, and a variable with its own heading takes its "Read by:" line. An unrecognized section, a missing "Read by:" line, or a variable that falls under neither rule exits 2 rather than passing quietly, so support cannot silently stop being checked.
The table of contents is built from headings, so putting the variables in it means each one needs its own heading. Every variable now has an h3 with its description, TOML key, CLI flag, and "Read by:" line, and the tables are gone. Group the variables by what they configure rather than by which clients read them: configuration file, connection, TLS, gRPC metadata, Codec Server, then the two CLI-only groups. "Client settings" was not a phrase this documentation uses, and the page is about environment variables either way. Lead with the intro's precedence order from highest to lowest, and link Temporal Client to the encyclopedia entry. Because support now lives on every variable, the checker drops its per-section rules and reads only "Read by:" lines. A variable reintroduced as a table row carries no such line, so the checker rejects the row instead of leaving its support unchecked.
The drift check runs weekly, so a failure on the cron schedule has nowhere to surface. Add it to the Slack notification list. The existing guard already excludes pull_request runs, which this workflow also has, so PRs to the page report once on the PR rather than twice. Retry each source fetch up to four times with exponential backoff, since an unattended weekly job should not report a GitHub blip as drift. A 404 is not retried: it means the file moved, and the check has stopped covering that implementation until the path in SOURCES is updated.
…/temporalio/documentation into consolidate-env-config-reference
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
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.
Environment variables that configure a Temporal Client were documented in two tables that disagreed with each other and with the code. This replaces both with one reference, and adds a check that keeps it honest.
The problem
docs/references/client-envrionment-configuration.mdxlisted 16 variables and omittedTEMPORAL_PROFILE.docs/cli/setup-cli.mdxlisted 10, and presentedTEMPORAL_TLS_CA,TEMPORAL_TLS_CERT, andTEMPORAL_TLS_KEYas current names. The CLI treats those as legacy compatibility shims (cliext/client.go). It also carried two comments apologizing for being out of sync.temporal envvariables or the six legacy TLS names.What changed
One reference at
/references/client-environment-configurationcovering all 26 variables, withTOML key,CLI flag, andSupported bycolumns. The Temporal CLI is a Temporal Client, so its variables live here too, marked by scope rather than split onto a separate page.Ten variables that were documented nowhere are now covered:
TEMPORAL_PROFILE,TEMPORAL_CLIENT_AUTHORITY,TEMPORAL_ENV,TEMPORAL_ENV_FILE, and the six legacy TLS names.The
setup-cli.mdxtable becomes a pointer. Its#environment-variablesanchor is preserved, and it picks up the shell-variable versustemporal envdistinction requested in temporalio/cli#776.The misspelled filename is fixed. The URL comes from the frontmatter
id, so it is unchanged and needs no redirect.The drift check
bin/check-env-config-table.jsextracts variable names from every implementation that reads them and fails when they disagree with the table:sdk-goTEMPORAL_CLIENT_AUTHORITYsdk-rustcoresdk-typescriptprocess.envdirectly rather than through coresdk-javacliimplied-envflag mappings and the legacy TLS namesIt catches three drift modes: a variable in a source but not the table, a variable in the table that nothing reads, and a
Supported bycell claiming a client that does not read the variable. All three are negative-tested.Descriptions stay hand-written. Only the variable and support data is checked, so prose is never regenerated.
It runs weekly and on demand, plus on PRs touching the page or the checker. It is not a blanket per-PR gate because it fetches sources over the network, and a GitHub outage should not block unrelated documentation PRs.
Notes for review
Supported bycolumn records which clients read a variable, not whether they fully honor it. The existing caveat onTEMPORAL_TLS_DISABLE_HOST_VERIFICATIONis preserved for that reason.TEMPORAL_TLSmaps to the inverted TOML keytls.disabled, which the description calls out.temporal envlegacy. The CLI markstemporal configEXPERIMENTAL and has itstemporal envdeprecation commented out pendingconfigGA, so neither is presented as superseding the other.yarn buildpasses. Since this repo setsonBrokenLinks: 'throw'andonBrokenAnchors: 'throw', that confirms the rename kept all inbound links working.Closes temporalio/cli#697 and temporalio/cli#776 from the documentation side. temporalio/cli#1138 takes the other approach, generating a separate CLI-only page, and should be closed in favor of this.
┆Attachments: EDU-6843 Consolidate environment variable docs into one reference