Add Artifact Registry format pages

What does this MR do?

Adds a formats section with five pages: an index plus one page per format.

Page Covers
formats/_index.md The four formats and their clients, a repository-type table, how to choose between Docker and OCI, republish behavior per format
formats/maven.md Clients, republish rules, limits, delete path, the five Maven error strings, the server-identifier gotcha
formats/npm.md Clients, package naming rules, republish rules, limits, delete path, the commands that return nothing, the trailing-slash gotcha
formats/docker.md Which artifacts a Docker repository accepts and rejects, image naming and the 255-character path cap, tags, limits, delete behavior
formats/oci.md How OCI differs from Docker on push, naming, limits, delete behavior

Why this comes out of draft

Two questions blocked these pages. Both are answered now, based on an engineering review from @10io, checked against the artifact-registry repo and gitlab-org/cli.

Corrections from review

  • OCI proxying. The old pages said OCI can't proxy a public upstream. That was wrong. Remote repositories work for all four formats. The capability matrix is replaced with a repository-type table.
  • Upstreams. The old pages said the only available upstreams are Maven Central, npmjs.com, and Docker Hub. That was wrong too. A remote repository can proxy any HTTPS registry URL. Those three hosts are freshness pins that cache indefinitely, because they don't allow a published artifact to be overwritten.
  • Virtual repositories. Not available for any format. A create request returns 422. This was missing from the pages entirely and is now documented.

Also applied:

  • Every ## Configure your client section now has real steps built on glab artifact-registry login, per format.
  • formats/docker.md and formats/oci.md both state that the client path segment is container for both formats. docker and oci appear only in management API URLs.

Review notes

Two facts correct the engineering review itself:

  • glab artifact-registry get-token has no --registry flag. Its flags are --hostname, --duration, and --output.
  • glab artifact-registry login --npm exists and is documented. Yarn 2 and later read npmAuthToken from .yarnrc.yml, so the ~/.npmrc write doesn't cover them.

Open question: can you actually get a 500 deleting a virtual repository?

delete.md and troubleshooting.md both document a 500 when deleting a virtual repository. If create returns 422 for every format, there may be no way to reach that state. Those two topics may need to come out until virtual repositories land.

What the pages do cover, all verified against shipped code or the OpenAPI contract

  • The Docker versus OCI push rule, including the exact 400 MANIFEST_INVALID case: a Docker repository rejects a subject-less non-image artifact such as a Helm chart or a WebAssembly module with an empty configuration.
  • Republish behavior, which differs by format and surprises people. npm returns 409. Maven accepts a byte-identical re-upload and returns 409 after that, so a rebuilt JAR usually fails. Container tags can be re-pushed and the tag moves.
  • npm package naming rules, including the reserved names and the scoped-name check.
  • The 255-character cap on the full container path, separators included.
  • npm search and npm audit return nothing deliberately, so npm install keeps working.
  • docker search returns nothing, because the catalog endpoint is not implemented.
  • The two client gotchas that produce a bare 401: an npm authentication line whose URL does not match the registry line, and a Maven server identifier that does not match the repository.

Related to #626825 Parent epic: &21052

Testing

Re-run after the corrections above:

  • Vale at --minAlertLevel error (the CI gate): 0 errors.
  • Vale at --minAlertLevel warning: 0 warnings.
  • markdownlint: 0 errors.
  • lychee link check, including the new cross-page links: 0 errors.

Not verified against a running environment. Staging is not connected to Artifact Registry yet (#619481 (closed)).

Edited by Tim Rizzi

Merge request reports

Loading
Loading