## Closing summary Orbit and Artifact Registry both had customer-facing APIs that didn't appear in GitLab's public API reference, which put them at risk of shipping without accurate, reviewed public documentation. We published both specs at https://api.gitlab.com/rest/ and added the necessary infrastructure to keep them in step with each service's source, so they update automatically whenever the API changes. Customers now have a single place to find both APIs, and other services can follow the same setup to publish their own. ## DRI @abignotti ## Participants @cfeick ## Problem Orbit and Artifact Registry both ship consumer-facing HTTP APIs, and neither appears in GitLab's public API reference. - **Orbit** has no spec. Its `/api/v4/orbit/*` endpoints are Grape in the monolith and every one carries `hidden true` in its `desc` block, which is why grape-swagger omits them from the generated spec. Six endpoints are documented manually at https://docs.gitlab.com/api/orbit/; five more exist in the Grape source and are not. The Orbit team has confirmed the manual docs are behind the real surface. - **Artifact Registry** hand-authors two OpenAPI 3.1 documents, lints them in CI and contract-tests them, but publishes them only to an access-controlled Pages site, so no consumer outside the project can read them. Orbit's white-glove customer install was targeted for 2026-08-20. Once these APIs ship their shape is effectively public; changing it later means breaking changes for consumers, and neither team is likely to revisit API concerns soon after shipping. Both services diverged because no default existed to follow. Fixing these two is the immediate need; supplying the defaults so a third does not repeat it is tracked separately. ## Goal ### First iteration 1. Orbit's consumer-facing endpoints are generated from their Grape source, carry accurate response schemas, and are agreed with the Orbit team as to which of the eleven endpoints are public. 2. Artifact Registry's `api/openapi/v1.yaml` renders at https://api.gitlab.com/rest/, selectable alongside the GitLab REST spec. 3. Both specs redeploy automatically when the source spec changes, triggered from each service's own CI rather than by anyone remembering to. 4. Neither team is handed a spec and left. API Platform confirms with each that the published document matches what they actually need to expose. ### Long-term outcome - Both specs stay accurate without either team maintaining them by hand. - Breaking-change and policy checks run in both services' pipelines whenever their spec changes. - **Any per-service work done here that a third service would have to repeat is a defect, not a deliverable.** Where it cannot be avoided, it becomes an issue in the scaffolding epic rather than a pattern. ## Technical considerations - The ingestion loop is already list-driven. `src/config/specs.js` in https://gitlab.com/gitlab-com/gl-infra/api-docs is a declarative array — its own comment reads "The documents the reference renders, adding one is an entry here" — with a `gitlabFile(project, path, ref)` helper that pulls any GitLab repo file through the Files API. `fetch-spec.js` loops every spec in every declared locale. Adding a spec is a configuration change, not a code change. Closed under https://gitlab.com/gitlab-com/gl-infra/api-docs/-/work_items/37. - The OpenAPI 3.0 versus 3.1 version gap is also closed: https://gitlab.com/gitlab-com/gl-infra/api-docs/-/work_items/36. - **The monolith's change trigger already exists and is path-filtered.** `.gitlab/ci/api-docs.gitlab-ci.yml` in `gitlab-org/gitlab` defines `trigger-api-docs-pipeline`, which triggers api-docs' `main` pipeline on a push to the default branch that changes `doc/api/openapi/openapi_v3.yaml`. Orbit's endpoints generate into that file, so once they are unhidden their spec propagates with no new wiring — there is no Orbit-side trigger to build. - **Artifact Registry has no equivalent**, being a separate project, so that one does need wiring. Generalising it so no future service needs a bespoke setup belongs to the scaffolding epic. - `fetch_openapi_spec` runs on any api-docs default-branch pipeline, so specs also refresh incidentally whenever one runs, including from the daily Renovate schedule. A safety net, not something to design around. - Why Orbit's Grape endpoints are absent from the generated spec is known: `hidden true` in each `desc` block. If other namespaces do the same, the durable fix is the completeness check in https://gitlab.com/groups/gitlab-org/quality/-/work_items/432 and this epic should only fix Orbit. - Generating Orbit's spec from Grape matches how the monolith works, but it is provisional: whether GitLab's house model is generated-from-code or hand-authored-and-verified is owned by the epic "Establish one API definition model for all GitLab modular features" (https://gitlab.com/groups/gitlab-org/quality/-/work_items/465). If that decision goes the other way, Orbit follows it. ## Links **Contacts**: Angelo Rivera (Orbit), João Pereira (Artifact Registry) Artifact Registry: https://gitlab.com/gitlab-org/ops/artifact-registry Specs: `api/openapi/v1.yaml` (customer-facing management API) and `api/openapi/gitlab-v1.yaml` (monolith-to-AR service surface) Orbit: https://gitlab.com/gitlab-org/orbit/knowledge-graph REST surface: https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/orbit/data.rb Manual docs: https://docs.gitlab.com/api/orbit/ Multi-spec rendering (blocks this epic): https://gitlab.com/groups/gitlab-org/quality/-/work_items/433 <!-- STATUS NOTE START --> ## Status 2026-10-01 Work on this epic is basically done: both Artifact Central and Orbit API specs are now published in `api.gitlab.com/rest/`. Only one issue remains, which is an improvement on Orbit's spec. The 5 MRs from this issue are waiting for reviews. :clock1: **total hours spent this week by all contributors**: 20 :status: **TL;DR**: One week left, if the reviews come in time we'll be able to make it :tada: **achievements**: * The Artifact Central spec is now live at [api.gitlab.com/rest/](https://api.gitlab.com/rest/#description/introduction/artifact-registry/artifact-central) and the old Pages website that published it does not show it anymore, so there is only one SSOT! * The Orbit spec is now live at [api.gitlab.com/rest/](https://api.gitlab.com/rest/#description/introduction/artifact-registry/gitlab/tag/orbit) * The 5 MRs that improve the information in Orbit's spec are in review :issue-blocked: **blockers**: * :arrow_forward: **next**: * Merge the remaining MRs and close the epic _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/428#note_3934204511_ <!-- STATUS NOTE END -->