## :dart: Why Closed-beta clients cannot authenticate to the Artifact Registry with raw GitLab credentials; they exchange a credential for a short-lived JWT first ([ADR-020](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/020_authentication_flow/)). `glab` is the user-facing entry point for that exchange. Rails-side issuance (R1, `POST /api/v4/token_exchange`) is already shipped and AR-side validation is #218; this is the **client** side: the `glab ar` auth commands. Closed beta is **CC v1, same-boundary** (`.com <-> .com`, `SM <-> SM`, `Dedicated <-> Dedicated`) per ADR-020 revision 2. Background, the problem statement ([gitlab#595150](https://gitlab.com/gitlab-org/gitlab/-/work_items/595150)), the PoC, and competitive analysis live in gitlab-org&22012, whose CC v2 framing predates the CC-v1-first decision. ## :compass: What Refine and upstream the PoC auth commands into [`glab`](https://gitlab.com/gitlab-org/cli) as `glab artifact-registry`, with `ar` kept as an alias, scoped to the CC v1 path: - **`glab artifact-registry status`**: exchange a credential and print the token's issuer, subject, and expiry, so a user can confirm which identity and instance they are authenticated as before configuring any tool. Writes no credential to disk. - **`glab artifact-registry get-token`**: exchange a GitLab credential for a CC v1 JWT, output to stdout. Flags: `--hostname`, `--duration` (default 15m, up to 12h; shorter values are allowed, the server floor is 1 second), `--output`/`-F` (`text`/`json`, matching glab's existing `cmdutils.EnableJSONOutput` convention). No `--scope`: the token-exchange endpoint (`POST /api/v4/token_exchange`) takes no scope parameter, and ADR-020's token payload carries no role/scope claims — the Artifact Registry evaluates authorization per request (ADR-021), not from the token. - **`glab artifact-registry login --docker/--maven/--npm/--gradle/--sbt`**: wrappers that write a fresh JWT into the tool-specific credential file. All require `--registry`. - **`docker-credential-glab` CC v1 path**: mint a fresh JWT on every `get`, keeping token expiry transparent to Docker/OCI clients. Delivered as **six steps**, one command per merge request, following this project's convention for introducing new commands. Step numbers are stable references for merge request titles and review; execution follows the dependencies in the table below, not numeric order. We built a PoC a while ago, hosted in https://gitlab.com/jdrpereira/cli/-/tree/feat/ar-auth. ## :white_check_mark: Acceptance criteria Applies to every step: `make lint` and `make test` pass, `make gen-docs` output is committed alongside the source, each new command carries `text.ExperimentalString` so it is labeled EXPERIMENTAL in `--help` and in the generated docs, and the `ar` alias resolves for it. ### Step 1 — `status` - [x] `glab artifact-registry status` exchanges a credential against `POST /api/v4/token_exchange` and prints the token's issuer, subject, and expiry. - [x] `--hostname` selects the instance; without it, the configured instance is used. - [x] `--output json` emits the same three fields as JSON. - [x] Nothing is written to disk — the command is a check, not a login. - [x] The exchange omits `expires_in`, so the server's default lifetime (5 minutes) applies, since the token is only read for its claims. - [x] Tests drive a fake `token_exchange` endpoint rather than a live instance. ### Step 2 — `get-token` - [x] Only the bare token goes to stdout, so `TOKEN=$(glab artifact-registry get-token)` captures it cleanly; every diagnostic goes to stderr. - [x] `--duration` accepts values up to 12h, including shorter than 15m, and rejects values above 12h before any HTTP call. The default is 15m, defined as its own constant so the default and the ceiling can move independently. - [x] `--output json` emits the token together with its expiry. - [x] `--hostname` selects the instance. ### Step 3 — credential helper resolves artifact registries - [x] A new per-host key `artifact_registry_domains` is registered in `internal/config`'s `KeySchema`, user-settable, mirroring `container_registry_domains`. - [x] `glab auth docker-helper get` returns a freshly exchanged token for a registry listed under that key for some host. - [x] For a domain listed under **both** registry keys, the artifact registry is tried first and the container registry credentials are used only if that fails — so an artifact-registry setup cannot break a `docker pull` that worked before it. - [x] For a domain listed **only** under `artifact_registry_domains`, a failed exchange is reported as an error with no fallback. - [x] The credential is resolved from configuration only: `GITLAB_TOKEN` in the environment cannot change which identity mints the token. `CI_JOB_TOKEN` authentication inside CI still works. - [x] A configuration read failure is reported as itself, not as an unknown registry domain, and one unreadable host does not hide another host that lists the domain. - [x] Usable without any new command: `glab config set artifact_registry_domains <domain> --host <host>` followed by `docker pull` authenticates. - [x] A `Get`-level test pins the dual-listed precedence in both directions. ### Step 4 — `login --docker` - [x] Registers glab as the Docker credential helper for `--registry` and records the registry under the host's `artifact_registry_domains`, so Docker mints a fresh token per request. - [x] Access is verified before anything is written: a token is exchanged and discarded, and on failure no shim, no `credHelpers` entry, and no configuration key are left behind. - [x] `--registry` must be a non-empty bare hostname — a URL, a comma, or a control character is rejected. - [x] `--hostname` carrying a scheme or whitespace is rejected, and the value is used exactly as given rather than case-normalized, since configuration host lookup is an exact match. - [x] Unsupported platforms are rejected up front rather than reporting a login that cannot work. - [x] `--duration` is ignored and says so, because the credential helper exchanges its own token per request. - [x] Warns when the registry is also a configured container-registry domain. When the only available credential comes from the environment (which the credential helper ignores), the login fails rather than warns: the verification exchange fails and the error tells the user to run `glab auth login`. - [x] Honors `$DOCKER_CONFIG`, falling back to `~/.docker`. ### Step 5 — `login --maven` - [x] Upserts a `<server>` block into `~/.m2/settings.xml` keyed by `<id>`, authenticating as `__token__` with the exchanged token. - [x] When a block for that id already exists, only `<username>` and `<password>` are rewritten — `<configuration>`, `<filePermissions>`, and comments survive a token refresh. - [x] A file with no `<servers>` section gets one added before `</settings>`; a self-closing `<servers/>` is expanded into a real section. - [x] A `<servers>` element that cannot be edited safely is refused with an actionable message, rather than leaving the file with two `<servers>` elements. - [x] On every error path the file is left byte-for-byte intact. - [x] The file is written `0o600` and its directory `0o700`. - [x] `--registry-alias` defaults to a name derived from `--registry`; an explicit value is validated before use. ### Step 6 — `login --gradle/--npm/--sbt` - [ ] `--gradle` upserts `{alias}Url`, `{alias}Username`, and `{alias}Password` in `~/.gradle/gradle.properties`, preserving unrelated lines and their order. - [ ] `--npm` upserts `//{host}{path}/:_authToken=` in `~/.npmrc`, matched by exact line prefix so a lookalike domain cannot match. - [ ] `--sbt` upserts a `credentials += Credentials(...)` line in `~/.sbt/1.0/credentials.sbt`, recording the host **without** its port, which is what sbt and coursier match on. - [ ] All three write `0o600` files in `0o700` directories, and re-running updates the existing entry in place instead of duplicating it. ## :bar_chart: Status | Step | Description | MR | Status | Done | Assignee | Dependencies | |------|-------------|----|--------|------|----------|--------------| | Prereq | Docker credential-helper hardening: centralizes shim installation and the `credHelpers` write, refuses to replace another tool's credential helper, warns when an existing `docker login` is shadowed, propagates config read failures, writes the shim atomically. Carries no artifact-registry code | https://gitlab.com/gitlab-org/cli/-/merge_requests/3688 | ~"workflow::complete" | [x] | @sylviashen | — | | 1 | `status`: the token-exchange client (`internal/api/artifactregistry`), the parent command scaffolding, and claims output | https://gitlab.com/gitlab-org/cli/-/merge_requests/3693 | ~"workflow::complete" | [x] | @sylviashen | — | | 2 | `get-token`: bare token on stdout, `--duration`, `--output`/`-F` | https://gitlab.com/gitlab-org/cli/-/merge_requests/3695 | ~"workflow::complete" | [x] | @sylviashen | Step 1 | | 3 | Credential helper resolves artifact registries: the `artifact_registry_domains` per-host config key, the exchange path in the helper, the precedence rule for a domain listed under both registry keys, and an env-suppressed API client so `GITLAB_TOKEN` cannot decide which identity mints the token. Usable alone — the key is user-settable, so `glab config set` plus `docker pull` works | https://gitlab.com/gitlab-org/cli/-/merge_requests/3704 | ~"workflow::complete" | [x] | @sylviashen | Step 1; external: Prereq | | 4 | `login --docker`: the `login` command skeleton (flags, validation, dispatch) and credential-helper registration, verifying access with a discarded token exchange before writing any state | https://gitlab.com/gitlab-org/cli/-/merge_requests/3705 | ~"workflow::complete" | [x] | @sylviashen | Step 3; external: Prereq | | 5 | `login --maven`: upserts a `<server>` block into `~/.m2/settings.xml`, preserving user-added children across token refreshes | https://gitlab.com/gitlab-org/cli/-/merge_requests/3709 | ~"workflow::complete" | [x] | @sylviashen | Step 4 | | 6 | `login --gradle/--npm/--sbt`: three upsert rules over one shared line-file helper | https://gitlab.com/gitlab-org/cli/-/merge_requests/3710 | ~"workflow::in review" | [ ] | @sylviashen | Step 5 (`--gradle` needs `--registry-alias`) | ## :link: Dependencies - **Prerequisite — [cli!3688](https://gitlab.com/gitlab-org/cli/-/merge_requests/3688).** Fixes bugs in the existing `glab auth configure-docker` and `glab auth docker-helper` on `main`: silently replacing another tool's Docker credential helper, silently disabling an existing `docker login`, config read failures reported as missing configuration, and a non-atomic shim write. It carries no artifact-registry code, so it lands independently of this work; steps 3 and 4 build on the shared shim installation and `credHelpers` write it introduces. - **Unsplit implementation — [cli!3662](https://gitlab.com/gitlab-org/cli/-/merge_requests/3662).** All six steps are extracted from it. Kept as a draft reference until the extraction is finished. - **Server half — #218** (AR-side token validation). ## :question: Open questions for the Artifact Registry These came out of implementation review and cannot be resolved client-side: - **What realm does the registry send in `WWW-Authenticate`?** The sbt writer records `Credentials("Artifact Registry", host, ...)`. Ivy matches stored credentials on (realm, host), so a mismatch makes sbt send the request unauthenticated and fail with a 401, with nothing wrong at login time. The value is unverified against a live registry. - **Should the token-exchange `audience` be a URI?** It is currently `gitlab-artifact-registry`. A bare string is awkward for future services that need to verify these tokens, but the server decides which audiences it accepts, so this needs a server-side change first — changing it client-side alone makes every exchange fail. - **Is the token churn acceptable for closed beta?** The Docker credential helper mints a fresh JWT on every `get`, by design, so expiry stays transparent to OCI clients. That is one token exchange per registry request. The alternative, caching tokens on disk, adds a credential-at-rest surface the CLI currently avoids. ## :open_book: Notes - The code lands in [`gitlab-org/cli`](https://gitlab.com/gitlab-org/cli); this issue tracks it from the closed-beta program, the same way #221 tracks the Rails-side work. - **Out of scope**: CC v2 / cross-boundary (multiple Self-Managed instances against one SaaS Artifact Registry) is a follow-up; management commands (`glab ar repo/artifact ...`) remain in gitlab-org&22012. - Reference epic gitlab-org&22012 holds the background, PoC, and competitive analysis (`aws codeartifact login`, `gcloud auth configure-docker`, `az acr login`). - Server half: #218 (AR-side token validation). - `POST /api/v4/token_exchange` is currently gated behind the `gate_token_exchange_endpoint` feature flag (`gitlab_com_derisk`, per-user actor, default off) — enable it to develop or test against a live instance.