Loading
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.
- Authentication scheme. Same answer as !252858 (closed). ADR-009 is correct, and the UI's Maven and Gradle snippets are a known defect (gitlab-org/ops/artifact-registry#1039 (closed)).
- Registry URL. Still undecided (hostname:
gitlab-org/ops/artifact-registry#1000 (closed), path prefix:
gitlab-org/ops/artifact-registry#268), but it no longer
blocks these pages. Every page uses a
<registry_host>placeholder and says the hostname and path prefix aren't final.
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 clientsection now has real steps built onglab artifact-registry login, per format. formats/docker.mdandformats/oci.mdboth state that the client path segment iscontainerfor both formats.dockerandociappear only in management API URLs.
Review notes
Two facts correct the engineering review itself:
glab artifact-registry get-tokenhas no--registryflag. Its flags are--hostname,--duration, and--output.glab artifact-registry login --npmexists and is documented. Yarn 2 and later readnpmAuthTokenfrom.yarnrc.yml, so the~/.npmrcwrite 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_INVALIDcase: 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 returns409after 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 searchandnpm auditreturn nothing deliberately, sonpm installkeeps working.docker searchreturns 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 issues
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