## 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 | **Blocked** on !3457. | | 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`; connection and proxies follow merge request 2. | ## 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 **Blocked on !3457.** !3602 merged on 2026-08-17, so the custom HTTP headers content is settled. !3457 then took its place as the blocker: it is README-only, and it rewrites two of the subsections this merge request moves, the `GitLab access variables` table and `Token and environment variable precedence`. Splitting this merge request to ship only the sections !3457 does not touch was considered and rejected. !3457 has been open since 2026-06-24 and is close to merging, and landing this first would leave a Support Team contributor resolving a conflict against a README section that no longer exists. This merge request stays whole and waits. One merge request covering the remaining README sections: - Configuration levels and configuration search order. - GitLab Self-Managed and GitLab Dedicated instances, mTLS certificates, and self-signed certificates. - The environment variable tables, and token and environment variable precedence. - Provider-specific proxy examples, given their own page rather than accumulating in a README section. From !3602 this is the custom HTTP headers content and the Google Identity-Aware Proxy example using `valueFromEnv` or `valueFromCommand`. The transparent SSH `ProxyCommand` configuration that lets `git` and `ssh` connect through IAP was in the original plan but never landed in the README, so it needs writing 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. - **Connection and proxies**: wait on merge request 2. 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/ ├─ 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 four 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 ships first; configuration, connection, and proxies follow in a single merge request once !3457 merges. - **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)