docs(auth): add an organization-wide setup recipe

Kai Armstrongrequested to merge
docs/org-wide-auth-setup into main

What does this MR do and why?

A customer rolling glab out to their developers worked out, over several rounds with us, that the instance details can be deployed as environment variables so each user only runs glab auth login --web. They confirmed it works end to end on v1.118.0. Nothing writes that down, so the next organization has to rediscover it.

This adds a Standardize setup across an organization section to the authentication page: the variable set, what each variable suppresses, and the caveats that are not obvious from the variable reference. The environment variable reference on the configuration page already recommends this approach in the abstract, so it now links to the worked example.

The part worth reviewing

The recipe is not a transcription of what the customer sent. Their working set omits GITLAB_HOST, and I verified against v1.118.0 that the same set run outside a Git repository signs in to the wrong instance:

Environment Result
Customer's set, no GITLAB_HOST - Signing into gitlab.com (issued a real device code against gitlab.com)
Same plus GITLAB_HOST - Signing into gitlab.example.com

Their run worked because they were inside a repository whose remote points at their instance, so remote detection supplied the host. On a freshly provisioned machine, before anything is cloned, it would silently target gitlab.com. GITLAB_HOST is therefore in the documented set, with a note explaining why.

Three other things the section states that are easy to get wrong:

  • GITLAB_API_HOST and GITLAB_SSH_HOST are still required when they match GITLAB_HOST. The prompts skip on the variable being set, not on the value differing, so dropping them as redundant reintroduces two prompts.
  • The re-authentication confirm has no suppressing flag or variable, so the one-command claim holds for a first login only. Documented rather than glossed.
  • The personal access token path needs no glab auth login at all, which is the simpler option for anyone not using OAuth.

How to set up and validate locally

markdownlint-cli2 docs/source/authentication.md docs/source/configuration.md
vale docs/source/authentication.md
lychee --offline --include-fragments docs/source/authentication.md docs/source/configuration.md

The host-selection behavior above reproduces with:

cd "$(mktemp -d)"   # outside any Git repository
GLAB_CONFIG_DIR="$(mktemp -d)" GITLAB_API_HOST=gitlab.example.com GITLAB_SSH_HOST=gitlab.example.com \
  GLAB_API_PROTOCOL=https GLAB_GIT_PROTOCOL=ssh GLAB_NO_PROMPT=true \
  glab auth login --device
#   -> Signing into gitlab.com

MR acceptance checklist

  • markdownlint, vale (0 errors) and lychee pass on both pages. The remaining vale warnings on authentication.md are pre-existing and outside this change.
  • make gen-docs produces no drift; both pages are hand-maintained.
  • Anchors verified: authentication.md#standardize-setup-across-an-organization and configuration.md#environment-variables both resolve under lychee --include-fragments.
  • Content is anonymized. No customer name, hostname, client ID, username, or file path.

🤖 Generated with Claude Code

Merge request reports