docs: add Artifact Registry beta user documentation

Tim Rizzirequested to merge
trizzi/docs-user-artifact-registry-beta into main

Summary

Moves the Artifact Registry beta user documentation into this repo, at docs/user/.

These 15 pages were first written as five stacked MRs in the gitlab-org/gitlab monolith, under doc/user/artifact_registry/. Technical writing flagged that AR docs belong in the AR repo, not the monolith. That decision was made months ago. This MR carries it out.

The five monolith MRs are superseded and closed:

Where these pages publish

The docs-gitlab-com Hugo config mounts ../artifact-registry/docs to content/artifact_registry. So these pages render at docs.gitlab.com/artifact_registry/user/. Artifact Registry is already registered in data/products.yaml in docs-gitlab-com.

Pages

15 pages, about 1,615 lines:

  • Overview (_index.md, replaces the existing placeholder page)
  • Get started
  • Repositories
  • Authenticate
  • Roles and permissions
  • Delete
  • Limits
  • View usage
  • Troubleshooting
  • API reference (api.md)
  • Four format pages, under docs/user/formats/: Maven, npm, Docker, OCI

Link handling

Links between these 15 pages stay relative. The move did not change them.

Twelve links pointed at monolith pages. Those are now absolute https://docs.gitlab.com/... URLs. That matches the pattern other external docs products use, such as Orbit and GitLab Runner. All twelve URLs return HTTP 200.

Review status

Engineering already reviewed this content, on the monolith MRs. Technical writing has not reviewed it yet.

Governing ADRs

None. No ADR covers where user-facing documentation lives. The placement comes from technical writing: docs/user/ in this repo, published to docs.gitlab.com through the docs-gitlab-com Hugo mount.

Testing

Both docs/user lint gates pass locally:

Check Command Result
Markdown lint markdownlint-cli2 --config user.markdownlint-cli2.yaml 'docs/user/**/*.md' 0 errors
Vale vale --config=.vale-user.ini --minAlertLevel error docs/user 0 errors, 0 warnings, 0 suggestions

Every absolute docs.gitlab.com link was checked with curl. All return HTTP 200.

docs:hugo-build will confirm the pages render. Hugo is not installed locally, so that check was not run locally.

Two open questions for the reviewer

1. Where should the API page live?

docs/user/api.md documents two API surfaces:

  • The GitLab GraphQL API, served by the monolith.
  • The Artifact Registry management API, served by the AR service.

Right now the whole page moved here. Should the GraphQL half stay in the monolith instead?

Related: the monolith's API index at doc/api/api_resources.md had a row for Artifact Registry, added on a superseded MR. That row is gone now. It could come back as a link out to this page.

Say which option you prefer.

2. Should the URL prefix change?

These pages land at docs.gitlab.com/artifact_registry/user/get_started/.

GitLab Runner, GitLab CLI, and GitLab Chart get their own URL prefix because they are separate installable products. Artifact Registry is a GitLab.com feature that users reach from the GitLab UI. So this URL sits oddly next to docs.gitlab.com/user/packages/.

  • Now: changing the Hugo mount target in docs-gitlab-com is a one-line edit.
  • After publish: changing it means adding redirects.

Worth settling before these pages go live.

Follow-up: navigation

Navigation is a separate MR, in gitlab-org/technical-writing/docs-gitlab-com. Nothing links to these pages until data/en-us/navigation.yaml gets entries.

Proposed spot: Use GitLab > Deploy and release your application > Packages & Registries, as a sibling of "Package registry" and "Container registry".

Merge request reports