Bound Tags API offset retrieval with FindAllTags

What happened

During a GitLab Dedicated incident, repeated Tags REST API requests contributed to Gitaly saturation. For non-search offset requests on page 2 onward, Rails fetched every tag through FindAllTags, then kept only the requested page.

What this MR does

This MR connects the bounded retrieval added in Part 1 to the Tags REST API, behind the project-scoped bounded_tags_api_offset_pagination feature flag, disabled by default.

  • The finder fetches the first page × normalized per_page tags and returns only the requested page. For page 5 with 100 tags per page, it fetches up to 500 tags and returns tags 401–500.
  • The pager returns that page without slicing again and builds headers using repository.tag_count.
  • Page-one cursor behavior, explicit keyset pagination, search, and other finder callers remain unchanged.
  • Disabling the flag restores full retrieval and array-derived totals on later pages.

Limitations

  • Deep offset pages still fetch increasingly large prefixes. Repository-wide sorting in Gitaly remains.
  • Stale cached counts can produce inaccurate totals or navigation links. This already affects page 1; this MR extends the same count usage to later pages. Returned tags remain independent of the count.
  • Search still retrieves all tags before filtering.
  • The mitigation remains inactive until the feature flag is enabled.

How to set up and validate locally

  1. Use a project with at least seven tags and an API token with repository read access.
  2. Enable the flag in the Rails console:
    Feature.enable(:bounded_tags_api_offset_pagination, project)
  3. Request:
    GET /api/v4/projects/:id/repository/tags?order_by=name&sort=asc&page=2&per_page=2
    Confirm it returns the third and fourth tags. Inspect FindAllTags in a debugger: its limit should be 4.
  4. Follow the next link. Confirm it returns the fifth and sixth tags with RPC limit 6.
  5. Disable the flag:
    Feature.disable(:bounded_tags_api_offset_pagination, project)
    Repeat the requests. Results should match, but later pages should fetch all tags without an RPC pagination limit.
Edited by Emma Park

Merge request reports

Loading
Loading