## Problem Creating a modular feature today produces no OpenAPI spec, no API pipeline, and no docs registration. Nothing tells a team what its API should look like, and nothing checks it afterwards. The result is the divergence the Orbit and Artifact Registry epic is now paying for across two services. It should not need a third. **The point is not that every feature has a spec somewhere. It is that publishing one costs us nothing.** Two propagation mechanisms already exist and neither is being used for this. - **Into services**: modular features are generated from https://gitlab.com/gitlab-com/gl-infra/common-template-copier, LabBench's `bench` scaffold wraps it, and `copier update` plus Renovate push template changes into services already generated. One change reaches both new and existing features. - **Out of services and into the docs**: api-docs already ingests, builds and deploys from a declarative list of specs. What it cannot do is discover a service on its own. The missing piece is the join between them: a feature declares its spec once, and both the api-docs registration and the redeploy trigger follow from that declaration. Today both are hand-done per service. `gitlab-org/gitlab` is the only project with a trigger into api-docs today — a properly path-filtered one, worth copying rather than reinventing — and every new service needs its own until this is in the scaffold. ## Goal ### First iteration 1. A feature can register its spec with api-docs without anyone hand-writing a merge request. 2. A scaffolded feature emits the api-docs redeploy trigger from its own CI by default. 3. The convention is written: where a feature's OpenAPI spec lives, and how it gets published. 4. It reaches existing features through `copier update` and Renovate, not by hand. 5. It is proven by onboarding one service end to end with **no API Platform involvement**. That last clause is the acceptance criterion, not a nicety. ### Long-term outcome - A new modular feature gets a spec location, a validation pipeline and docs registration by default. - Its spec appears at https://api.gitlab.com/rest/ without per-service work. - Breaking-change and policy checks apply automatically. - API Platform's spec conventions are what LabBench's transport-layer abstraction builds on, rather than something developed in parallel to it. ## Technical considerations - There is a ready-made pattern for the registration half. https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/35 shipped as `bench register` (closed 2026-09-03). It opens a merge request against `infra-mgmt` appending the service to `data/projects/release-platform/repos.yaml`. A scaffold that already knows how to open a registration MR against a central repo is the mechanism; api-docs is a second target for it. - The plumbing is language-agnostic. A `src/config/specs.js` entry is a YAML-shaped configuration change and a redeploy trigger is CI configuration; redocly lints YAML regardless of runtime. ADR 008 has landed (Proposed). Validation is the Redocly CI component from https://gitlab.com/gitlab-org/gitlab/-/work_items/624044, the same for every runtime. ADR 008 requires no codegen step, so nothing in this epic fragments per language. - api-docs' `fetch_openapi_spec` job runs only on default-branch pipelines and has no pipeline schedule. Downstream triggers from other projects' CI are the intended mechanism and are already accepted. - Goal 4 depends on https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/48. `bench scaffold` runs only `copier copy` and never `copier update`, so an existing bench cannot pick up later template changes. https://gitlab.com/gitlab-com/gl-infra/common-template-copier/-/work_items/21 is blocked by it. Renovate still bumps pinned versions in files a service already has. ## Links Definition model decision: ADR 008 (Proposed) https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/theseus_platform_vision/decisions/008_openapi_specification_for_modular_http_apis/ It came from the epic "Establish one API definition model for all GitLab modular features" https://gitlab.com/groups/gitlab-org/quality/-/work_items/465 Scaffold: https://gitlab.com/gitlab-com/gl-infra/common-template-copier LabBench: https://gitlab.com/gitlab-org/lab-bench/bench api-docs: https://gitlab.com/gitlab-com/gl-infra/api-docs **Contacts**: Elliot Forbes; LabBench framework owner to confirm.