Reuse ListRefs branch heads in the conflict check
What does this MR do and why?
The branch existence check already resolves every branch of a merge request list page with one ListRefs call per repository, and that response carries each branch's commit. The conflict check then looks up the source branch head again with a FindCommit per merge request.
Behind reuse_listrefs_branch_heads, the API merge request lists let the conflict check read the source head from that same ListRefs batch. In a request-spec probe, a group page of 32 merge requests went from 30 Gitaly calls to 3, with identical responses and SQL. On GitLab.com, FindCommit is about half of the Gitaly calls made by GET /groups/:id/merge_requests.
References
- Investigation: #631601
- Rollout issue: #634669 (closed)
Screenshots or screen recordings
Not a UI change.
How to set up and validate locally
- Enable the flag in a Rails console:
Feature.enable(:reuse_listrefs_branch_heads) - Call the group list for a group with open merge requests and note
gitaly_callsfor the request inlog/api_json.log:curl --header "PRIVATE-TOKEN: <token>" "http://gdk.test:3000/api/v4/groups/<id>/merge_requests?state=opened&per_page=100" - Disable the flag, wait a minute for the flag cache, repeat the call, and compare.
gitaly_callsis higher by oneFindCommitper merge request that reaches the conflict check, anddetailed_merge_statusvalues are identical.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
Detailed context for AI agents
Change
app/models/repository.rb:lazy_ref_target(ref)(private): a BatchLoader likelazy_ref_exists?that loads each ref's target instead oftrue.lazy_ref(ref): queues the ref inlazy_ref_targetwhen the flag is on, and in master'slazy_ref_exists?when it is off.branch_exists?,tag_exists?andGitlab::Git::RefPreloader.preload_refs_for_projectgo through it, so existence checks and branch head reads share oneListRefscall.batched_ref_target(ref): returns nil when the flag is off or there is no repository, otherwise queues the refs collected for the project and reads the target from the batch.reuse_listrefs_branch_heads?(private): the flag check, memoized per repository withstrong_memoize_attr.RefPreloaderre-queues every collected ref on eachbranch_exists?call, so an unmemoized check ran once per ref per call (2,856 evaluations on a project page of 40 merge requests, 1 with the memo).
lib/api/merge_requests.rb#serializer_options_forsets thebatched_branch_heads: trueentity option for the three list endpoints (GET /merge_requests,GET /groups/:id/merge_requests,GET /projects/:id/merge_requests), not forview=simple.API::Entities::MergeRequestBasic#detailed_merge_statuspassesoptions[:batched_branch_heads]toDetailedMergeStatusService, which addsbatched_branch_heads: trueto the check params only when it is set.CheckConflictStatusServicereads the source head fromsource_project.repository.batched_ref_target(source_branch_ref)when the param is set, and falls back tomerge_request.source_branch_sha(FindCommit) otherwise, or when there is no source project or the batch has no target.
Why this shape
- Grape serializes entities after the endpoint block returns (
Gitlab::Json::GrapeFormatter), so anything scoped with a block aroundpresenthas ended beforedetailed_merge_statusruns. Entity options live on the entity objects, so they hold through that and throughpresent_cached. Precedents: theissuable_metadataoption inAPI::Entities::IssuableEntity, andCi::Pipeline#lazy_ref_commit(a request-lifetime BatchLoader of branch heads with no invalidation, originally shipped behind a flag). - The previous revision of this MR stored
ListRefstargets inGitlab::SafeRequestStoreand cleared them in threeRepositoryexpire hooks. Those hooks miss in-request branch moves:commit_files,merge_to_branch,ff_merge,cherry_pickandrevertgo throughwith_cache_hooks, which only firesafter_create_branch, andrebasehas no hook. Its opt-in also sat in the entity class, so it covered everyMergeRequestBasicandMergeRequestrender including write endpoints andMergeRequestAiEntity, and it only saved calls when the commits check had run first withref_existence_check_gitalyon. - Rejected:
Gitlab::GitalyClient.allow_ref_name_cachingaroundpresent: needs the body dumped inside the block, and the flag would also switch the check in controllers already under ref-name caching.- grape-entity
serializable: true: serializes each entity before the next one queues its issuable metadata, which turned that batch into an N+1 (71 to 129 SQL on a page of 30). - Setting
source_branch_sha=: it is the importer's override and changessource_branch_reffor every caller. ListCommitsByRefName: one more RPC per repository, and theListRefsresult goes unused.
Staleness
- The head comes from the same
ListRefssnapshot thatbranch_missing?already trusts in the same check run. List GETs write no refs: their mergeability rechecks are async. - A push from another process between the
ListRefscall and the render gives the same result as master, whereFindCommitis also a point-in-time read. - The diff-head comparison itself stays. It came in with !215908 (merged) to stop the merge button showing as ready before a push is processed, and no cheaper "push not processed yet" signal exists.
- A branch ref pointing at an annotated tag object would read as
checking, which is pathological.
Feature flag
- Actor: the repository's project, checked once per repository. For the head read that is the source project, so the batch and the check always agree.
- Flag off:
lazy_refuses master'slazy_ref_exists?,batched_ref_targetreturns nil, and the conflict check usessource_branch_sha. The extra work is one memoizedFeature.enabled?per repository, an unused option key and check param, and.present?on the existing boolean. - Flag on: every
branch_exists?andtag_exists?caller for that project uses the target-loading batch, with the same RPC and the same result. Only the list endpoints read the targets.
Verification
- Specs, run in an isolated spec slot:
check_conflict_status_service_spec.rb(20),detailed_merge_status_service_spec.rb(33),merge_request_basic_spec.rb(7),repository_spec.rb#batched_ref_target,#branch_exists?,#tag_exists?(15), and the new list examples inspec/requests/api/merge_requests_spec.rb(3). 0 failures. - Throwaway request-spec probe, flag off against flag on. The fixture had a fork merge request, a merge request whose branch moved after its diff was built, a deleted source branch and a real conflict.
- Group list (32 merge requests, with and without
with_merge_status_recheck): 30 to 3 Gitaly calls,FindCommit27 to 0. GET /merge_requests(32): 30 to 3.- Project list (22), plain and
present_cachedpaths: 21 to 2. - Every
detailed_merge_statuswas equal, response bodies were byte-identical, and SQL counts were identical. - Flag evaluations on a project page of 40 merge requests: 1 per request.
- Group list (32 merge requests, with and without
- A 70-scenario break matrix against master's
CheckConflictStatusServiceandlazy_ref_exists?(fork, moved, deleted, prefix-only and unicode branches, importer sha override, missing repository, flag andref_existence_check_gitalystates, in-request ref writes, every entry point that must not opt in) passes. ci:job_tokens:check_policies,gitlab:openapi:v3:check_docs,gitlab:cells:routes:updated_checkandgitlab:permissions:validatepass on this commit.
Production context
Kibana, GET /api/:version/groups/:id/merge_requests, one hour on 2026-10-29:
- The conflict check is about 3.7% of the endpoint's request time, at about 10.5 ms per merge request on average.
FindCommitis about 49% of the endpoint's Gitaly calls and 26% of its Gitaly server time (p50 0.7 ms, p90 10.7 ms), at about one per conflict check.
Not included
present_cachedmisses serialize one merge request at a time, so issuable metadata is not batched on those (109 against 71 SQL on a page of 22). That is master behaviour.- The project list cache is keyed on
updated_atandmerge_status, so it can serve a pre-push status until the refresh runs. Also master behaviour.
Related
This is one of four changes from the investigation in #631601, each behind its own gitlab_com_derisk flag. !263467 (merged) (security policy check) and !263468 (merged) (approval check) are merged; the lock check change is !266187 (merged). !266966 (merged) removes the group endpoint's response cache flag and does not overlap with this diff.