## Context Nothing records which GitLab and Artifact Registry (AR) version pairs work, and nothing detects an unsupported pair before the first call that breaks. The two release on separate cadences. On GitLab.com both deploy continuously, and the AR UI sits behind the `artifact_registry_ui` flag. On Self-Managed and Dedicated, operators upgrade each on its own schedule, and Dedicated runs GitLab behind GitLab.com. This serves the Dedicated deployment row (P0) of the GA epic https://gitlab.com/groups/gitlab-org/-/epics/22707, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/605684. That issue's negative acceptance criterion requires a change-communication path for every behavior change reaching Dedicated, which cannot toggle feature flags. The monolith spec template and every monolith spec that calls AR defer that compatibility work (client capability detection plus a "not available" UI state) to Self-Managed and Dedicated. The deferral ends with the Self-Managed closed beta (19.5, 2026-10-15) and the Dedicated beta track (2026-10-16). The GitLab Dedicated tooling readiness review raised this as Question 6. ## What exists on main Each line holds at `origin/main` `d7fcf10e6` (2026-10-01) unless it names another source. - `docs/dev/self-managed-limitations.md`, row 9 of `## What should be lifted`: asks for a published matrix, because `artifactRegistry.apiUrl` is only a URL, with no version constraint, negotiation, or check. It says nothing tracks the GitLab-to-AR half. - `docs/dev/self-managed-install.md`: the header records the only set tested together (walked 2026-09-22: GitLab 19.4.0 on chart 10.4.0, AR chart 2.82.1, and `iam-data-access` chart 1.55.3). `## Scope` says no matrix is published. `## Upgrading` moves AR to 2.86.2 under the same GitLab and checks the version through four AR-side signals. - `docs/dev/gitlab-api.md`, `## Backward compatibility`: changes within `/api/gitlab/v1` are additive only, clients must tolerate unknown fields and enum values, and a breaking change waits for `v2`. - `api/openapi/gitlab-v1.yaml` and `api/openapi/v1.yaml`: both `info.description` blocks state that rule. The GitLab API's nine operations report neither AR's version nor its capabilities. Every management API operation declares `x-gitlab-lifecycle: experiment` (`docs/dev/api-style.md`, `### Lifecycle status`). - `.gitlab-ci.yml`: `lint:openapi` lints each OpenAPI document alone, and `buf:breaking` compares protos with the target branch. No job compares an OpenAPI document with its earlier version. - `internal/gitlabapi/handler.go` and `internal/gitlabapi/response.go`: an unrouted `/api/gitlab/v1/` path and an unknown namespace both answer `404` with envelope code `not_found`. Only the message differs. - `internal/metrics/buildinfo.go`, `internal/server/server.go`, and LabKit v2.60.0 `httpserver`: AR's link-time version appears on every log record and, on the probe listener (port 9090), in `gitlab_artifact_registry_build_info` on `/-/metrics` and in the `/-/liveness` and `/-/readiness` bodies. Nothing under `internal/` sets a version header on the application listener that `apiUrl` names. - `internal/auth/tokenexchange/` and `internal/relationships/types.go`: AR verifies GitLab's token-exchange JWTs with IAM's `userauth` library, which rejects any `ver` but `1`. AR accepts only `organization` and `gitlab_federated` as `gitlab.origin`, and it answers every rejected token with the same `401`. - ADR-020, `## Token payload (R3)`: `ver` changes only on a breaking payload change, so additive claims such as `gitlab.job` keep it at `1`. - `docs/specs/monolith/TEMPLATE.md`, `## Compatibility (multi-version)`: defers client capability detection and the "not available" UI state to Self-Managed and Dedicated. `git grep -n -i 'capability detection' -- docs/specs/monolith/` returns ten deferral lines, across the template and monolith/S02 to S07, S10, and S14. - monolith/S02: the client pins `/api/v1`, ignores unknown response fields, and sends `User-Agent: GitLab/#{Gitlab::VERSION}` on every request. `## Error mapping` has no row for an unsupported AR. On `gitlab-org/gitlab` `master`, `ee/lib/artifact_registry/client.rb` (last changed in `a34d28319`, 2026-09-28) has no version or capability check. - monolith/S06, `## Compatibility (multi-version)`: specifies one skew case per value. An AR older than the gate patch omits the key, and the view hides the row or renders the tab's empty state. - monolith/S10, `## Error cases`: a condition endpoint the deployed AR predates answers `404`, and the page section shows the error. The slice adds no capability detection. monolith/S01's `### States` table has no row for an unsupported AR. - ADR-014: under `### Rails-side components`, navigation gating reads the persisted mapping and the cached slug and status instead of calling AR on every page load. Open question 1 asks how the AR URL reaches Rails on Self-Managed and who owns that configuration contract. It never mentions capability detection, though the template and monolith/S04, S05, S06, and S14 cite it for that. - `docs/dev/releases.md` and `.releaserc.json`: `semantic_release` cuts releases from the mirror's `main`, and a `feat:` merge bumps the minor. Canonical holds 290 tags on commits dated September 2026 (166 minor or major, 124 patch, counted 2026-10-01). `v2.0.0` came from a boot-behavior change, the `feat(authz)!` commit that fails closed on an unconfigured authorization posture. `.releaserc.json` accepts `{major}-{minor}-stable` maintenance branches, and canonical has no branch matching `stable` (2026-10-01). - `internal/managementapi/pact_provider_test.go`: verifies the management API against Rails consumer contracts published per GitLab version, behind `//go:build contract`. No CI job runs it. - `docs/roadmap/beta.md`, `## Scope and status`: Self-Managed Gate 1.5 lists a release manifest for modular components, which the roadmap lists as AR-only and not started. It blocks the release after the 2026-10-15 launch. - Outside the repository, the release manifest design (https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/release_manifest/) freezes one compatible version per modular component for each GitLab release, in the public https://gitlab.com/gitlab-org/release/manifests/released project. Its `19/4/0.json` lists only `release-platform-canary` (2026-10-01). ## Change Operators on Self-Managed and Dedicated can read which AR versions each GitLab version supports. GitLab paired with an AR that lacks what it calls renders a clear not-available state instead of failing on the first call that breaks. Product first picks the document: the per-pair matrix this issue proposed, or the compatibility contract from the [2026-09-30 comment](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1468#note_3930861448). Under the contract, the release manifest records the AR version bundled with each GitLab release. Every AR patch on that AR minor stays compatible with that GitLab version, and every GitLab patch on that GitLab minor stays compatible with the bundled AR. The [2026-09-29 comment](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1468#note_3921924645) says the release manifest already provides this. The manifest holds one AR version per GitLab release and no other pairing, which is the contract's input. Under either choice, detection with graceful degradation covers the three GitLab-to-AR edges: the `/api/gitlab/v1` calls, the `/api/v1` management API the UI calls, and the token-exchange tokens GitLab issues. The AR-to-IAM half (https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1327) and GLAZ, which ships pinned inside AR's chart, stay out of scope. ## Acceptance criteria 1. Decision for product, since no spec covers it: this issue's description records the choice between the per-pair matrix and the compatibility contract, with its date. Under the contract, it also names the AR version line that stays compatible with each GitLab minor. Nothing defines that line at `d7fcf10e6`: `.releaserc.json` accepts `{major}-{minor}-stable` branches but canonical has none, and the install guide's upgrade crosses AR minors (2.82.1 to 2.86.2 under GitLab 19.4.0). 1. Decision for product, since no spec covers it: the description names the document's home and who updates it each release. The candidates are `docs/user/` (published to docs.gitlab.com on merge), `docs/dev/` (where row 9 lives), and the release manifest's public record. A matrix gains an entry per AR release (290 tags on commits dated September 2026), and the contract takes its per-release input from the manifest record. 1. The published document states each edge's rule, and each matches its cited source: additive-only changes within `/api/gitlab/v1` (`docs/dev/gitlab-api.md`) and within `/api/v1` (`api/openapi/v1.yaml`), and a token-exchange token AR accepts only with `ver` `1` and a `gitlab.origin` of `organization` or `gitlab_federated` (ADR-020, `internal/relationships/types.go`). 1. Decision for the S17 owner, since neither S17 nor `docs/dev/api-style.md` covers it: whether the `/api/v1` additive-only rule binds Self-Managed and Dedicated pairs while every operation declares `x-gitlab-lifecycle: experiment`. The published document states the ruling. 1. The published document names which pairs count as unsupported, with at least one concrete pair. GitLab 19.4.0 is the first release whose client carries `disable_namespace` and `enable_namespace` (tags containing `685255d3d118` on `gitlab-org/gitlab`, read 2026-10-01), and v1.217.0 is the first AR release serving those condition endpoints. GitLab 19.4.0 with an older AR hits the `404` monolith/S10 `## Error cases` describes. 1. Decision for the S33 owner, since S33 names no such read: what GitLab reads to learn what the deployed AR serves, whether an AR version, a capability list, or the per-key presence monolith/S06 already relies on. Status and envelope code cannot carry it on `/api/gitlab/v1`, where an unrouted path and an unknown namespace both answer `404` `not_found`. A new read lands in S33 and `api/openapi/gitlab-v1.yaml` before any code, with a contract test in `internal/gitlabapi`. 1. Decision for the monolith/S02 and monolith/S03 owners, since neither spec has a row for it: how enforcement fails. The amended specs state whether the client refuses every call to an AR outside the supported set or each slice degrades only the feature it cannot serve, which typed error and GraphQL error carry the refusal, and what an inconclusive detection read renders. If the result gates navigation, the gate reads it from a cache, as it reads the cached slug and status (ADR-014, `### Rails-side components`), so a page load makes no AR call for it. 1. With the unsupported pair criterion 5 names, the AR UI renders the not-available state that a new monolith/S01 `### States` row specifies, in place of the error message or empty result that monolith/S02's error mapping gives a missing endpoint. A named Jest or RSpec test renders it. 1. For a pair inside the supported set, the monolith/S02 acceptance criteria keep holding: the existing examples in `ee/spec/lib/artifact_registry/client_spec.rb` pass unedited. 1. Every line `git grep -n -i 'capability detection' -- docs/specs/monolith/` returns describes the active mechanism, where all ten at `d7fcf10e6` call it deferred. The template lists the concern as active, because planners add compatibility steps only for concerns marked active. 1. Row 9 of `## What should be lifted` in `docs/dev/self-managed-limitations.md` and the no-matrix `## Scope` bullet in `docs/dev/self-managed-install.md` link the published document, and row 9 names this issue for the GitLab-to-AR half. 1. Decision for the AR maintainers, since no spec covers it: what checks the additive-only rule, which this issue says has no check. The options are a CI job comparing `api/openapi/gitlab-v1.yaml` and `api/openapi/v1.yaml` with the target branch, as `buf:breaking` does for protos, and CI provider verification against each supported GitLab version's consumer contracts. The published document names the chosen check, or states that review alone enforces the rule. ## Specs and ADRs - [ADR-009, GitLab API](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/009_api_design.md#gitlab-api): the surface stays backward compatible across the platform versions it serves. - [ADR-014, Rails-side components](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/014_frontend_to_artifact_registry.md#rails-side-components): navigation gating reads cached state instead of calling AR on each page load. - [ADR-014, Open questions](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/014_frontend_to_artifact_registry.md#open-questions): question 1, the Self-Managed AR URL and its configuration contract. - [ADR-020, Token payload (R3)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/020_authentication_flow.md#token-payload-r3): the `ver` and `gitlab.origin` claims. - [S33, Surface conventions](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S33-gitlab-api.md#surface-conventions): additive changes from the first shipped platform client onward. - [GitLab API, Backward compatibility](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/gitlab-api.md#backward-compatibility): the additive-only rule and the half that binds clients. - [API Style, Breaking changes](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/api-style.md#breaking-changes): the breaking-change catalog and the deprecation process. - [Monolith spec template, Compatibility (multi-version)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/TEMPLATE.md#compatibility-multi-version): the deferral this issue ends. - [monolith/S02, Compatibility (multi-version)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/S02-ar-ruby-client.md#compatibility-multi-version) and [Error mapping](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/S02-ar-ruby-client.md#error-mapping): the client contract that detection extends. - [monolith/S03, Compatibility (multi-version)](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/S03-graphql-foundation.md#compatibility-multi-version): the resolver side of the deferral. - [monolith/S01, States](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/S01-vue-app-shell-and-composition-surfaces.md#states): where the not-available state gets its row. - [monolith/S10, Error cases](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/S10-activation-and-deactivation.md#error-cases): the `404` from a condition endpoint the deployed AR predates. - [Release manifest design](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/release_manifest/): the source of bundled versions under the contract. ## Dependencies - Criteria 1 and 2 come first, because the document's content and home depend on them. - No issue tracks AR's release manifest entry: a 2026-10-01 search of AR issues for "release manifest", "Release Framework", and "release-tools" found none. Under the contract, file one before the document lands, because the contract names the bundled AR version the manifest record holds, and `19/4/0.json` holds none. Self-Managed Gate 1.5 needs the same entry. - https://gitlab.com/gitlab-org/gitlab/-/work_items/629666, then https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/305, only if criterion 12 adds provider verification: the first records that the Rails job publishing consumer contracts has never succeeded, and the AR provider test fails without a published contract version. - https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1327: the AR-to-IAM half, out of scope, with no ordering. - https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1329: records no policy for breaking change management. The published document covers that row's GitLab-to-AR part, with no ordering. ## First step After product rules on criteria 1 and 2, the first MR writes the document where criterion 2 puts it, with criterion 3's edge rules, and points row 9 of `docs/dev/self-managed-limitations.md` and the install guide's `## Scope` bullet at it. Detection starts with criterion 6's ruling, because the monolith/S03 and monolith/S01 amendments build on it. That ruling lands as an S33 amendment if GitLab gets a new read, and as a monolith/S02 amendment otherwise. ## Original description ## Summary State which GitLab versions work with which Artifact Registry versions. Detect an unsupported pair at runtime, instead of letting it fail on the first call that breaks. ## Problem GitLab and the registry release on their own cadences. On GitLab.com they stay close: both deploy continuously, and the UI is behind the `artifact_registry_ui` flag. On Self-Managed and Dedicated they drift apart. Each is upgraded on its own schedule, and Dedicated runs GitLab behind GitLab.com. Nothing records which pairs work. GitLab reaches the registry through `artifactRegistry.apiUrl`, which is only a URL, with no version check anywhere ([`docs/dev/self-managed-limitations.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/self-managed-limitations.md), item 9). The only tested pair is the one [`docs/dev/self-managed-install.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/self-managed-install.md) walked. The registry side has a rule but no check. Changes to `/api/gitlab/v1` are additive only ([`docs/dev/gitlab-api.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/gitlab-api.md#backward-compatibility), [ADR-009](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/009_api_design.md)). The monolith spec template defers capability detection to Self-Managed and Dedicated ([`docs/specs/monolith/TEMPLATE.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/monolith/TEMPLATE.md), "Compatibility (multi-version)"). That deferral ends with the Self-Managed closed beta (2026-10-15) and the Dedicated Beta track (2026-10-16, [&1065](https://gitlab.com/groups/gitlab-com/gl-infra/gitlab-dedicated/-/epics/1065)). ## Proposal 1. Publish the matrix: which GitLab versions each registry version supports. Say where it lives and who updates it on each release. 1. Cover every GitLab-to-registry edge: the `/api/gitlab/v1` calls, the management API the UI calls, and the token-exchange tokens GitLab issues. 1. Enforce it: version or capability detection in the monolith client, and a clear "not available" state in the UI for an unsupported pair. ## Out of scope - The registry-to-IAM Data Access half. [#1327](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1327) tracks it. - GLAZ. It ships pinned inside the registry's chart. ## Context Raised in the Dedicated tooling readiness review, Question 6: https://gitlab.com/gitlab-org/architecture/readiness/-/merge_requests/168#note_3903625561