[Batch 4] Add tier annotations to Create API endpoints

What does this MR do and why?

Adds route_setting :tier, :premium to 51 Create REST API routes. This is the fourth MR in a series that annotates Premium and Ultimate routes. The first two are !259422 and !259753 (merged). The third covered security and compliance.

This is documentation only. The setting becomes x-gitlab-tier in doc/api/openapi/openapi_v3.yaml, so API users can see which subscription tier an endpoint needs. Nothing reads it at runtime. There is no behavior or permission change. Free endpoints get no annotation.

What changed

  • 51 routes in 13 files, all Premium.
  • Each route gets a plain route_setting :tier, :premium above its route_setting :authorization. Grape route settings don't cascade, so each route sets its own.
  • doc/api/openapi/openapi_v3.yaml gains 51 x-gitlab-tier: premium lines. Nothing else changes in that file.
How the tier was chosen

The code is the source of truth. The docs are a cross-check. The rule comes from !259422. Annotate the lowest tier at which the endpoint does something useful. If an endpoint is gated lower than the feature that makes it take effect, use that feature's tier.

A tracer recorded licensed-feature checks while the request specs ran (13 spec files, all passing). All 51 routes match the tier in the docs.

Routes Basis
Group and project push rules (8) Tracer recorded push_rules gate
Project aliases (4) Tracer recorded project_aliases gate
Project approval rules (5), project approval settings rules (4) Tracer recorded merge_request_approvers / admin_merge_request_approvers_rules gates
Group approval rules (3) check_feature_availability on merge_request_approvers
Group and project MR approval settings (4) Policy prevents admin_merge_request_approval_settings without merge_request_approvers
Pull mirror (3) project.mirror? requires repository_mirrors; returns 400 without it
MR approval rules (5), project approvals (2), approval state and POST approvals (2) Rule applied, see reviewer note 1
Group repository storage moves (6) Rule applied, see reviewer note 2
Group protected branches (5) See reviewer note 3

Reviewer notes

  1. Approvals routes without a license check. MR approval rules, project approvals, and the approval state and POST approvals routes have no license check in the API, so they accept requests without a license. But approvals are only enforced when merge_request_approvers (Premium) is licensed. ApprovalState#approval_needed? returns false otherwise (ee/app/models/approval_state.rb:63). Annotated Premium per the rule. This matches the docs.
  2. Group repository storage moves. These are admin-only with no license check. They move group wiki repositories, which need Premium group_wikis. Premium per the rule. This matches the docs.
  3. Group protected branches. The API only checks admin_group. Enforcement (Project#group_protected_branches) has no license check, so Free namespaces can use the feature through the API. Only the UI checks group_protected_branches (Premium). I annotated Premium, which is the intended tier and what the docs say. The missing API check looks like a bug. It is reported to group::source code in a separate issue: . This MR does not change behavior.
Tracer note

Some routes reported incidental feature checks from custom-role spec examples, for example custom_roles on group protected branches. These are not the tier gate, so they were ignored.

How to set up and validate locally

  1. Run bin/rake gitlab:openapi:v3:generate. The diff should only add x-gitlab-tier: premium lines.
  2. This MR adds 51 lines. On its own, grep -c x-gitlab-tier doc/api/openapi/openapi_v3.yaml gives 54 (was 3). The count is higher if earlier MRs merged first.
  3. RuboCop is clean on the changed files.

Related to #631956

Merge request reports

Loading
Loading