## Decision (2026-09-08) The bare-slug URL structure stands for Closed Beta: no prefix. The rationale is in the decision comment below. Two follow-ups: 1. This issue is repurposed as the GA-blocking evaluation below. 1. The [ADR-015](https://internal.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/015_slug_policy/) reserved slug pool is extended now, while the deployment is .com-only and every existing slug is inspectable; that window closes at the first Self-Managed/Dedicated release. ## GA evaluation: serve namespace slugs as subdomains Evaluate moving slugs to subdomains entirely (`<slug>.artifact-registry.gitlab.com`), the option that removes the root path space problem instead of working around it. Slugs are valid DNS labels by construction ([ADR-015](https://internal.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/015_slug_policy/)), so the option is open and additive: a new protocol can be served on subdomain hosts while apex path URLs stay grandfathered. Scope: - Wildcard DNS and certificate issuance and rotation. - Cloudflare proxying of wildcard custom hostnames. - Host-based routing in the service and in GATE. - Client UX: `docker login` and image names, npm and Maven registry URLs. - Self-Managed and Dedicated operator burden (DNS and certificates). - Migration and dual-serve: grandfather apex path URLs vs cut over while the customer set is small. - Side benefit: per-slug cache partitioning (the #1070 class of problem). Outcome: adopt with a migration plan executed before GA, or reaffirm bare slugs at the apex and record why in ADR-009/ADR-015. --- ## Original question (settled for Closed Beta, 2026-09-08) ### Context Client API URLs place the namespace slug as the first path segment (`https://artifact-registry.gitlab.com/<slug>/<format>/<repo>/...`, [ADR-009](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/009_api_design/)). Route space is protected by reserving names at the slug level instead of prefixing URLs: [ADR-015 (internal)](https://internal.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/015_slug_policy/) hardcodes `-`, `api`, `app`, and `^v\d+$` as protocol-reserved slugs, with new internal endpoints under `/-/`. During the ADR-009 internal API review ([!20309](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/20309#note_3541557371)), an alternative was proposed: prefix the slug with a reserved segment (e.g. `n/<slug>/`) so the root path space stays free forever, avoiding the reserved-keyword gaps GitLab Rails experienced (missed keywords forcing migrations). See the [original suggestion](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/20309#note_3540527016) and prior settlement in [artifact-registry!34](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/34#note_3212066968) and [gitlab#593368](https://gitlab.com/gitlab-org/gitlab/-/work_items/593368). ### Why this is gated on Closed Beta go-live Slugs and URLs are immutable by design. Once the first external customer bakes a registry URL into `.npmrc`, `pom.xml`, Dockerfiles, or CI configuration, the URL structure is permanent. This is the last point where changing it is cheap. The question affects every client endpoint, so it is deliberately decoupled from the internal API definition in !20309 (internal endpoints already live under `/api/internal/v1` and are unaffected by the outcome). ### Pros of a reserved prefix (`n/<slug>/`) 1. The entire root path space stays free forever; no future keyword can collide with a customer slug. 1. Removes the ADR-015 frozen-list constraint: the protocol-reserved list cannot safely grow after release, since the same binary ships to Self-Managed and Dedicated and existing slugs there cannot be inspected. 1. Removes the residual risk of a future protocol mandating a root path that is also a valid slug. Under the bare-slug design, the fallback for such a collision is router workarounds in the binary, which ADR-015 itself describes as trading simplicity for fragility; a prefix removes the need for workarounds entirely. 1. Dispatch needs no reserved-word check: the first segment is always a literal. 1. Industry precedent exists among multi-format artifact managers: JFrog Artifactory (`/artifactory/`), Sonatype Nexus (`/repository/`), Azure Artifacts (`/_packaging/`), and AWS CodeArtifact (format prefixes) all place a fixed segment before customer-defined names. ### Cons 1. A permanent extra segment in every client-facing URL, exactly the URLs designed to be short and stable. 1. Inflates OCI image references (the prefix lands inside the image name: `.../n/<slug>/...`), reviving the UX concern that shaped the current design. 1. Uniformity is not achievable anyway: management already lives under `/api/v1/` and OCI under `/v2/`, so only non-OCI client URLs would change. 1. Container-style registries universally place the customer namespace at the root and manage collisions with reserved names instead: Docker Hub (reserves `library`), GHCR, Quay (reserves `build`/`trigger`/`tag` at repository level), ECR, ACR, Harbor, and Cloudsmith. Google Artifact Registry, the closest analog (multi-format cloud SaaS), is also namespace-first on `pkg.dev`. 1. The reserved-name mechanism already covers the known cases: `/-/` for internal endpoints, `^v\d+$` for versioned protocol roots, `api`, `app`. ### Outcome Discuss and decide before Closed Beta go-live: - **Reaffirm** the bare-slug structure: record the decision and rationale in ADR-009/ADR-015 and close. - **Adopt a prefix**: amend ADR-009, ADR-015, and ADR-022 before any external customer receives a registry URL. **Note:** Competitor insight above was generated based on a quick :robot: led investigation. Needs confirmation.