## Problem Commit 7e409a603e0b (#593084) added `route_setting :tier, :premium | :ultimate` for Grape endpoints. `config/initializers/gitlab_grape_openapi.rb` maps it to an `x-gitlab-tier` field in `doc/api/openapi/openapi_v3.yaml`. It is documentation-only. Nothing enforces it at runtime. Almost no routes use it yet. Only 16 routes have it (policy store, one vulnerability route, group epics). Only 3 of those are visible in the OpenAPI spec. The rest are hidden. So the OpenAPI spec cannot tell readers which endpoints need a paid tier. The RuboCop cop `API/RouteSettingTier` (`rubocop/cop/api/route_setting_tier.rb`) only validates the value. It does not require the setting. ## Proposal Annotate every paid route that appears in the OpenAPI spec: 308 routes (218 Premium, 90 Ultimate). Free endpoints need no annotation. ### Principle: code is the source of truth - No route gets a tier without code evidence. - Docs are a cross-check. When docs and code disagree, code wins and the doc is fixed in the same MR. - Example: epic discussions and related epics are documented as Ultimate, but the code gates them on Premium features (`epics`, `related_epics`). ### Two kinds of change **1. Plain insert (266 routes).** Add `route_setting :tier, :<tier>` above the route's `route_setting :authorization`, like `ee/lib/api/epics.rb:129`. **2. Conditional tier on shared CE/EE loops (42 routes at 25 sites).** One CE definition generates both Free and paid routes, because EE appends paid resource types to the loop. Each generated route is a separate path in the OpenAPI spec, so the tier can differ per route. Example: `lib/api/notes.rb` produces 35 routes. | Resource | Routes | Tier | |---|---|---| | Issue, MR, snippet, project wiki notes | 20 | Free | | Epic and group wiki notes | 10 | Premium | | Vulnerability notes | 5 | Ultimate | Fix: carry an optional `tier:` on the EE-side entry and emit it in the CE loop. CE code never names EE classes. - EE side: `NoteableType.new(::Epic, ..., tier: :premium)` in `ee/lib/ee/api/helpers/notes_helpers.rb`, or `with: { tier: :premium }` on the group hook mounts. - CE side: `route_setting :tier, x.tier if x.tier`. Affected CE files: `lib/api/notes.rb`, `award_emoji.rb`, `wikis.rb`, `resource_label_events.rb`, `hooks/*`, `integrations/integratable_operations.rb`. ## Scope Counts as of master `a1eca5d6cb3b`. | | Routes | |---|---| | Total Grape routes | 2,116 | | Hidden, in `excluded_api_classes`, or grape-swagger internal | 269 | | **In scope (appear in the OpenAPI spec)** | **1,847** | | Free: no change | 1,459 | | Paid: to annotate | 308 (218 Premium, 90 Ultimate) | | Already annotated | 3 | | Need owner verification | 31 | | Not a tier question (AI/Duo add-on gated, Geo node-to-node) | 46 | ## Plan Eight MRs. Route counts may shift after code verification. | # | MR | Routes | Scope | |---|---|---|---| | 1 | Plan (pilot; also builds and validates the tracer) | 28 | Epics, epic issues/links/boards, iterations, EE parts of boards/milestones/to-dos | | 2 | CE shared loops | 47 | Conditional tier for notes, award emoji, wikis, label events, hooks, integrations; plus `group_hooks.rb` | | 3 | Security & compliance | 49 | Vulnerabilities, dependencies/SBOM, security scans, attestations, status checks, compliance/security settings, audit events | | 4 | Create | 51 | Approval rules/settings, protected branches, push rules, aliases, mirrors, storage moves | | 5 | Auth & access | 47 | Member roles, identities, SAML/LDAP links, enterprise users, group credentials | | 6 | CI/CD & Geo | 55 | Runner controllers, agent URL config, merge trains, protected environments, deployments, releases, dependency proxy, Geo | | 7 | Analytics & AI | 31 | Group activity, code review analytics, DORA, search, Orbit, knowledge graph, AI external agents | | 8 | Guardrail (last) | - | Spec requiring a tier or allowlist entry on every visible `ee/` route; flags shared definitions with mixed tiers; cop docstring update | ## Per-MR checklist - [ ] Run the tracer on the MR's spec files. Annotate only routes with a recorded gate. - [ ] Insert `route_setting :tier`. - [ ] Regenerate `openapi_v3.yaml` with `bin/rake gitlab:openapi:v3:generate`, separately from v2. Rebase and regenerate on conflicts. - [ ] Confirm the `x-gitlab-tier` count rises by exactly the MR's route count. - [ ] Run RuboCop on changed files. - [ ] MR description lists each route, tier, gate feature, docs tier, and any doc fixes. ## Out of scope Follow-ups, not part of these MRs. - **31 routes need owner verification:** - 14 docs-vs-code conflicts (epic discussions, related epics, compliance external control status). - 12 instance-admin features with only an admin check in the endpoint (Zoekt, Elasticsearch, Geo nodes, LDAP). - 5 deprecated `managed_licenses` routes. - **46 non-tier routes:** - 37 AI/Duo routes gated by add-on rather than tier. Decide whether they need their own annotation. - 9 Geo node-to-node routes. Candidates for `excluded_api_classes`. - **About 64-70 Free endpoints with Premium/Ultimate-only parameters or response fields** (for example `PUT /projects/:id`, `GET /issues`, protected branches). These stay Free at the route level. Marking them needs a parameter-level annotation. - **Doc fixes:** vulnerability notes routes are undocumented. The epic discussions tier in `doc/api/discussions.md` is likely wrong. <details> <summary>How the routes were classified</summary> **Listing routes** - Listed every route at runtime from `API::Base.descendants`, the same source as the OpenAPI generator. Recorded source file and line. **Finding tiers** - Parsed `- Tier:` blocks in `doc/api/*.md`, per page and per section, and matched them to routes. - Cross-checked licensed-feature checks in code (endpoint files, helpers, `before` blocks, policy permissions). Mapped them to tiers through `ee/app/models/gitlab_subscriptions/features.rb`. **Source of the 308 paid routes** - 255 come from docs. - 53 come from code only (undocumented). - Only about 116 currently have code confirmation: about 63 from static license-check grep and 53 from reading the code. - About 190 rest on docs alone. - The docs are sometimes wrong (see epic discussions and related epics above). **Verification: the tracer** - A throwaway script loaded with `rspec -r`. It is not committed. - It records every `License.feature_available?` call (what `stub_licensed_features` stubs) per API request. - Calls are keyed by `caller_id`, which is set to the Grape endpoint id in `lib/api/api.rb:102`. The response status is recorded too. - A feature is a gate for a route when false gives 403/404 and true gives 2xx. - Route tier = highest tier among its gates. - 80 of 85 affected files (298 of 308 routes) have request specs. **Sequencing** - The tracer is built and validated in the pilot MR (epics). - Each later MR runs it on its own spec files before annotating. </details>