## Problem Authentication content for `glab` lives only in the project README, under [Authentication](https://gitlab.com/gitlab-org/cli#authentication). The docs site section [Authenticate with GitLab](https://docs.gitlab.com/cli/#authenticate-with-gitlab) contains two sentences and then links back to the README. That section is generated, not authored: the intro blocks of `docs/source/_index.md` are hardcoded string writes in `cmd/gen-docs/docs.go:571-575`. Consequences: - Readers searching `docs.gitlab.com` for `glab` OAuth, personal access token, or proxy instructions don't find them. - The README is the default destination for every new authentication and configuration topic, so it keeps growing. This came up in !3602, which adds a custom HTTP headers section for authenticating proxies. ## Decision The pages live in this project, under `docs/source/`, as hand-authored Markdown alongside the generated command reference. `docs-gitlab-com` clones this project (`data/products.yaml`) and mounts the whole `docs/source/` directory as `content/cli` (`config/_default/hugo.yaml`) with no per-file allowlist, so a new `docs/source/authentication.md` publishes at `https://docs.gitlab.com/cli/authentication/` on its own. The only change needed in `docs-gitlab-com` is the navigation entries, because navigation controls the sidebar, not publication. Hand-authored pages are safe in that tree: `make gen-docs` prunes only Markdown carrying the generated marker (`generatedMarker`, `cmd/gen-docs/docs.go:46`; `pruneGeneratedPages`, `cmd/gen-docs/docs.go:132-149`). These would be the first hand-authored pages under `docs/source/`; all 288 files there today are generated. ## Status | # | Scope | State | |---|-------|-------| | 1 | Authentication | **Merged** in !3692. `cli/authentication/` is live. | | 2 | Configuration, connection, and proxies | **In review** as a three-merge-request stack: !3813, !3814, !3815. | | 3 | Commands landing page | **Merged** in !3699. `cli/commands/` is live. | | 4 | Navigation entries in `docs-gitlab-com` | **Split.** Authentication merged as `docs-gitlab-com!2502`; `Commands` merged as `docs-gitlab-com!2504`; configuration, connection, and proxies follow the stack. | ## Proposal Four merge requests. #### 1. Authentication **Merged as !3692.** - Add `docs/source/authentication.md` from the README `## Authentication` section: the interactive-setup intro, OAuth (GitLab.com), OAuth (GitLab Self-Managed, GitLab Dedicated), personal access token, and CI job token. - Move the generated `## Troubleshooting` section ("Error: `invalid_client` during OAuth login") onto the same page, and drop it from `_index.md`. It's authentication troubleshooting, and it linked back to a README anchor this merge request removes. - Replace the README section with a pointer to the new page, and update the README table of contents and the `## Troubleshooting` pointer, which targeted `https://docs.gitlab.com/cli/#troubleshooting`. - Point the generated `## Authenticate with GitLab` block at the new page instead of the README anchor, then run `make gen-docs`. #### 2. Configuration, connection, and proxies **Unblocked and in review.** !3602 merged on 2026-08-17, settling the custom HTTP headers content. !3457 then took its place as the blocker, because it rewrote two of the subsections this work moves. **!3457 merged on 2026-08-27**, so the reason to keep this as one large merge request (sparing a Support Team contributor a conflict against a README section that no longer exists) no longer applies. It ships as a three-merge-request stack instead. The scope also needed a third page. The proposed navigation listed only `cli/connection/` and `cli/proxies/`, with no home for the configuration levels and search order, and no destination for the `#configuration` anchor links the move breaks. `cli/configuration/` fills that gap. - **!3813 — `cli/configuration/`.** Configuration levels, configuration search order, and platform-specific file locations. Also repoints three references to the removed README anchor `https://gitlab.com/gitlab-org/cli#configuration`: two in `docs/source/authentication.md`, and the `glab config` long help in `internal/commands/config/config.go` that generates the same line in `docs/source/config/_index.md`. CI runs `lychee --offline`, so these would have rotted silently. - **!3814 — `cli/connection/`.** GitLab Self-Managed and GitLab Dedicated instances, mTLS certificates, and self-signed certificates. - **!3815 — `cli/proxies/`.** Custom HTTP headers and the Google Identity-Aware Proxy example, one subsection per provider, with a note that the examples aren't exhaustive. Two items were cut from the original scope and follow separately: - **The environment variable tables** stay in the README for now. `docs/source/_index.md` already publishes an `## Environment Variables` table generated from the `help:environment` annotation in `internal/commands/root.go`, and that annotation is the tested source of truth: `internal/config/schema_drift_test.go` asserts every environment variable read in code appears there. The README tables are richer (they carry `config.yml` keys and defaults) but untested. Moving them as-is would put two overlapping tables on the docs site, so the follow-up has to decide whether the generated section becomes a pointer. - **The transparent SSH `ProxyCommand` configuration** that lets `git` and `ssh` connect through IAP never landed in the README, so it needs writing and testing against a real IAP instance rather than moving. #### 3. Commands landing page **Merged as !3699.** `docs/source/commands.md` is on `main` and `cli/commands/` is live. The `Commands` navigation parent needs a real page at `cli/commands/`, because every item in `navigation.yaml` has a `url` and there are no label-only grouping nodes. Move the `## Commands` section out of `_index.md` into `docs/source/commands.md`, generated by `gen-docs` from the root subcommand list so it stays in sync, and leave a pointer to it in `_index.md`. As a generated page it's pruned and rewritten on every `make gen-docs` run, so it doesn't need the hand-authored treatment the conceptual pages get. `docs/navigation-glab.yaml` is unaffected: `genNav` walks the cobra command tree only, so the new page never enters the generated block. The `Commands` parent is added by hand in `docs-gitlab-com`, outside the sentinels. #### 4. Navigation entries in `docs-gitlab-com` **Split by page, rather than one merge request at the end.** Each entry can merge as soon as its page is on this project's `main`, because that's what the sitemap check requires. `__tests__/navigation/check_menu_links.cjs` (via `make check-global-navigation`, in CI) fails on any navigation URL missing from the built sitemap, and the build clones this project's `main` branch. The reverse direction is safe: `scripts/pages_not_in_nav.cjs` only warns about published pages with no navigation entry, and never exits non-zero. - **Authentication**: merged as `docs-gitlab-com!2502`. `cli/authentication/` is live. - **Commands**: merged as `docs-gitlab-com!2504`, adding the parent entry at `cli/commands/` and the re-indent of the generated block. - **Configuration, connection, and proxies**: one entry per page, each merged after its page reaches `main` in this project. No `genNav` change is needed in this project. `genNav` walks the cobra command tree only and emits the list at zero indentation, and the splicer in `docs-gitlab-com` (`scripts/sync_glab_nav.cjs`) replaces only the lines between the `# BEGIN glab-cli` and `# END glab-cli` sentinels, taking its indentation from the BEGIN line. Hand-maintained entries added outside the sentinels survive `make sync-glab-nav`, and the generated block can be nested deeper without any change here. ## Proposed navigation Group the generated command reference under a `Commands` parent, so the new conceptual pages are not siblings of 283 command entries: ```plaintext GitLab CLI (glab) cli/ ├─ Authenticate with GitLab cli/authentication/ ├─ Configure the CLI cli/configuration/ ├─ Connect to your GitLab instance cli/connection/ ├─ Connect through a proxy cli/proxies/ └─ Commands cli/commands/ ├─ glab alias cli/alias/ └─ (44 top-level commands, 283 entries; the generated block, unchanged) ``` The sidebar collapses everything off the active trail, so today the `cli/` sidebar opens as a wall of 44 collapsed `glab *` entries. Grouping makes that landing page five items, and costs a click only on first entry: once a reader is on a command page, `Commands` is already expanded. Navigation hierarchy is independent of URL hierarchy. The sidebar trail is built by walking `navigation.yaml` keyed on `url` (`cmd/internal/build/build_page_metadata.go:109-155`), not from path segments, and 1,517 of 3,216 parent/child pairs in that file already have non-matching URLs. Grouping therefore needs no page moves and no redirects. ## Resolved questions - **How much does the README keep?** Installation instructions, and a short pointer to the docs site for each moved section. - **Do the configuration sections move at the same time?** No. Authentication shipped first. Configuration, connection, and proxies follow as a three-merge-request stack, one page each, now that !3457 has merged. - **Do the environment variable tables move with them?** No. They raise a duplication question against the generated table in `_index.md`, so they get their own follow-up. - **How do we keep the proxy examples maintainable?** One page for authenticating proxies, one subsection per provider, with a note that the examples aren't exhaustive. - **Does the navigation have to merge as one change at the end?** No. Splitting it per page is safe, because the sitemap check only cares that each URL in `navigation.yaml` is published, and pages with no navigation entry only produce an advisory warning. ## Related discussions Threads in !3602: - [Is the README the right place for this content?](https://gitlab.com/gitlab-org/cli/-/merge_requests/3602#note_3638272650) - [Should the examples live in a separate doc?](https://gitlab.com/gitlab-org/cli/-/merge_requests/3602#note_3642960129)