Add Artifact Registry authentication page

What does this MR do?

Adds doc/user/artifact_registry/authenticate.md. It documents how Artifact Registry authentication works, and how to configure each client.

Why this comes out of draft

One question blocked this page. It's answered now, based on an engineering review from @10io, checked against the artifact-registry repo and gitlab-org/cli.

ADR-009 is correct. Maven, Gradle, and sbt use Basic auth, with __token__ as the username and the exchanged token as the password. npm, yarn, pnpm, and all container clients use Bearer tokens. No client uses the Private-Token header. The UI's generated Maven and Gradle snippets are wrong and return 401. That's tracked in gitlab-org/ops/artifact-registry#1039 (closed), which also covers the missing sbt tool and the raw GITLAB_TOKEN placeholder.

The registry URL is still undecided (hostname: gitlab-org/ops/artifact-registry#1000 (closed), path prefix: gitlab-org/ops/artifact-registry#268), but it no longer blocks this page. The page uses a <registry_host> placeholder and says the hostname and path prefix aren't final. Everything after the registry handle is fixed by ADR-009.

What changed since the last review

  • Deleted a false claim that token exchange fails for an organization that hasn't activated Artifact Registry. No such check exists in the registry code.
  • Replaced the placeholder "Configure your package manager" section. It now documents glab artifact-registry login (glab 1.115.0 or later). The per-format links land with the format pages in !252859 (closed), because those pages don't exist on this branch yet.

What the page does cover, all verified against shipped code

  • The token-exchange flow, and that Artifact Registry never calls back to GitLab mid-request.
  • The credentials you can exchange: personal, project, and group access tokens, OAuth tokens, and CI/CD job tokens.
  • That deploy tokens are not supported, and why: the exchange issues tokens for users only, and a deploy token is not a user. ee/lib/api/authn/token_exchange.rb says so directly.
  • Token lifetime: five minutes by default, 12 hours maximum, no revocation before expiry.
  • The glab artifact-registry commands, and the one that matters most: only --docker refreshes tokens, because it registers a credential helper. Every other option writes one token and nothing refreshes it.
  • Which scheme each client uses, from the service's authentication dispatch table.

Related to #626825 Parent epic: &21052 Authentication epic: &22504

Testing

Re-run after the changes above:

  • Vale at --minAlertLevel error (the CI gate): 0 errors.
  • Vale at --minAlertLevel warning: 0 warnings.
  • markdownlint: 0 errors.
  • lychee link check: 0 errors.
Edited by Tim Rizzi

Merge request reports

Loading
Loading