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