docs: Move authentication documentation from the README to the docs site
Description
Authentication instructions for glab lived only in the project README. The docs site
section Authenticate with GitLab
held two sentences and then linked back to the README, so readers searching
docs.gitlab.com for OAuth or personal access token instructions didn't find them.
This is the first of four merge requests in #8486. It covers authentication only.
Changes:
- Add
docs/source/authentication.md, a hand-authored page that publishes athttps://docs.gitlab.com/cli/authentication/. It carries the README## Authenticationcontent: interactive setup, OAuth (GitLab.com), OAuth (GitLab Self-Managed, GitLab Dedicated), personal access token, and CI job token. - Move the
## Troubleshootingsection (Error: invalid_client during OAuth login) onto the same page. It's authentication troubleshooting, and it linked back to a README anchor this merge request removes. - Replace the README section with a pointer, and update the table of contents and the
README
## Troubleshootingpointer, which targetedhttps://docs.gitlab.com/cli/#troubleshooting. - Point the generated
## Authenticate with GitLabblock at the new page instead of the README anchor, and drop the generated troubleshooting block (cmd/gen-docs/docs.go). Regeneratedocs/source/_index.mdwithmake gen-docs.
Why a hand-authored page under docs/source/ is safe
make gen-docs prunes only Markdown carrying the generated marker
(pruneGeneratedPages, cmd/gen-docs/docs.go), so hand-authored pages in that tree survive
regeneration. docs-gitlab-com mounts the whole docs/source/ directory as content/cli
with no per-file allowlist, so the new page publishes without any change there.
Not in this merge request
- Configuration, connection, and proxy content. Blocked on !3602 (merged), which is still adding a custom HTTP headers section to the README.
- The
Commandslanding page atcli/commands/. - Navigation entries in
docs-gitlab-com. Those merge last, becausecheck_menu_links.cjsfails on navigation URLs missing from the built sitemap and the build clones this project'smainbranch. Until then the new page is published but not in the sidebar, which only produces an advisory warning frompages_not_in_nav.cjs.
Related issues and merge requests
- Closes part of #8486
Documentation
If this MR adds or updates CLI command documentation, follow the conventions in the
GitLab CLI (glab) documentation style guide,
run make gen-docs, and commit the updated files in docs/source/.