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 at https://docs.gitlab.com/cli/authentication/. It carries the README ## Authentication content: interactive setup, OAuth (GitLab.com), OAuth (GitLab Self-Managed, GitLab Dedicated), personal access token, and CI job token.
  • Move the ## Troubleshooting section (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 ## 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, and drop the generated troubleshooting block (cmd/gen-docs/docs.go). Regenerate docs/source/_index.md with make 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 Commands landing page at cli/commands/.
  • Navigation entries in docs-gitlab-com. Those merge last, because check_menu_links.cjs fails on navigation URLs missing from the built sitemap and the build clones this project's main branch. Until then the new page is published but not in the sidebar, which only produces an advisory warning from pages_not_in_nav.cjs.

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/.

Edited by Brendan Lynch

Merge request reports

Loading
Loading