Skip to content

Consolidate environment variable docs into one reference - #4989

Merged
lennessyy merged 10 commits into
mainfrom
consolidate-env-config-reference
Aug 5, 2026
Merged

Consolidate environment variable docs into one reference#4989
lennessyy merged 10 commits into
mainfrom
consolidate-env-config-reference

Conversation

@lennessyy

@lennessyy lennessyy commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

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.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. The CLI treats those as legacy compatibility shims (cliext/client.go). It also carried two comments apologizing for being out of sync.
  • Neither documented the temporal env variables or the six legacy TLS names.

What changed

One reference at /references/client-environment-configuration covering all 26 variables, with TOML key, CLI flag, and Supported by columns. 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.mdx table becomes a pointer. Its #environment-variables anchor is preserved, and it picks up the shell-variable versus temporal env distinction 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.js extracts variable names from every implementation that reads them and fails when they disagree with the table:

Source What it provides
sdk-go variables, plus the Go-only TEMPORAL_CLIENT_AUTHORITY
sdk-rust core variables inherited by Python, .NET, and Ruby through their bridges
sdk-typescript variables, read from process.env directly rather than through core
sdk-java variables, and the absence of codec support
cli implied-env flag mappings and the legacy TLS names

It catches three drift modes: a variable in a source but not the table, a variable in the table that nothing reads, and a Supported by cell 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

  • The Supported by column records which clients read a variable, not whether they fully honor it. The existing caveat on TEMPORAL_TLS_DISABLE_HOST_VERIFICATION is preserved for that reason.
  • TEMPORAL_TLS maps to the inverted TOML key tls.disabled, which the description calls out.
  • Second commit corrects wording that called temporal env legacy. The CLI marks temporal config EXPERIMENTAL and has its temporal env deprecation commented out pending config GA, so neither is presented as superseding the other.
  • yarn build passes. Since this repo sets onBrokenLinks: 'throw' and onBrokenAnchors: '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

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.
@lennessyy
lennessyy requested a review from a team as a code owner July 29, 2026 17:56
@vercel

vercel Bot commented Jul 29, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
temporal-documentation Ready Ready Preview Aug 5, 2026 12:02am

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

📖 Docs PR preview links

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.
@lennessyy
lennessyy merged commit e577862 into main Aug 5, 2026
16 checks passed
@lennessyy
lennessyy deleted the consolidate-env-config-reference branch August 5, 2026 00:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create an index of environment variables for the docs site

2 participants