docs(config): publish one environment variable reference

Kai Armstrongrequested to merge
docs/env-var-reference into main

What does this MR do and why?

Every KeySchema key already resolves from an environment variable, but the names were only listed in a hand-written table that existed in three partial copies: README.md, the generated docs/source/_index.md, and nowhere on the configuration page. Keys such as api_host, api_protocol, git_protocol, container_registry_domains and check_update appeared in none of them, so the supported way to configure glab centrally across an organization was undiscoverable.

This MR generates the reference from KeySchema into docs/source/configuration.md, the page that already explains system-wide configuration, and points README.md and _index.md at it. Token precedence moves to docs/source/authentication.md, which previously never mentioned GITLAB_TOKEN at all.

Bugs fixed along the way

Three GLAB_-prefixed names were already documented and read directly, but were absent from KeySchema, so Config.Get did not resolve them:

  • GLAB_GLAMOUR_STYLE — glamour_style had no EnvVars, so cfg.Get resolved the deprecated GLAMOUR_STYLE and ignored the documented name. glab mr view, glab issue view, glab release view and glab whatsnew were all reading the wrong variable.
  • GLAB_CHECK_UPDATE — the docs claimed it only forces a check. It disables them too, via isUpdateCheckEnabled.
  • GLAB_NO_PROMPT.

Also GITLAB_HEAD_REPO (internal/commands/mr/create/mr_create.go) was live and documented nowhere. The widened drift test found it.

Drift protection

TestGlabEnvVars_AreDeclaredOrDocumented previously only guarded GLAB_* names read through a literal os.Getenv, and auto-allowed anything derived from KeySchema on the premise that glab config help made it discoverable. That premise was half true: the help rendered the key but never the variable. This MR makes it honest by rendering the variable, widens the check to GITLAB_*, and adds the reverse assertion, so a variable that is read but undocumented, or documented but unread, now fails.

GITLAB_CI is excluded as a GitLab-provided CI variable. GITLAB_GROUP carries an explicit exemption because it resolves through flag binding rather than a literal os.Getenv, so the AST walk cannot see it.

Deliberately out of scope

  • GLAB_ aliases for the remaining unprefixed keys are a larger interface change and are split into a follow-up MR stacked on this one.
  • job_token is left out of the reference. It resolves from the environment like any key, but a job token is only usable inside CI, where it arrives as CI_JOB_TOKEN through auto-login. The authentication page covers that.
  • The root help:environment annotation is generated but still not rendered by the CLI. fang.Execute replaces cobra's help renderer, so RootHelpFunc never runs and the ENVIRONMENT VARIABLES, LEARN MORE and FEEDBACK sections are all dropped from glab --help. That is tracked separately. The per-key variables are visible today in glab config --help, because that text lives in Long, which Fang does render.

Screenshots or screen recordings

glab config --help now names the variable for each key:

- `container_registry_domains`: The domains of associated container registries. ...
  Scoped per host; set it with `--host`. Environment variable: `CONTAINER_REGISTRY_DOMAINS`.
- `check_update`: Allow glab to automatically check for updates ...
  Environment variables, first one set wins: `GLAB_CHECK_UPDATE`, `CHECK_UPDATE`.

How to set up and validate locally

make gen-docs   # idempotent; no diff on a second run
make check

# The glamour_style fix
D=$(mktemp -d)
GLAB_CONFIG_DIR=$D GLAB_GLAMOUR_STYLE=light ./bin/glab config get glamour_style  # was `dark`, now `light`

MR acceptance checklist

  • make lint and go test ./... pass.
  • markdownlint, vale (0 errors) and lychee pass on the changed pages.
  • make gen-docs committed and idempotent.

Merge request reports