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

Screenshots or screen recordings

Not a UI change.

How to set up and validate locally

  1. Enable the flag in a Rails console:
    Feature.enable(:reuse_listrefs_branch_heads)
  2. Call the group list for a group with open merge requests and note gitaly_calls for the request in log/api_json.log:
    curl --header "PRIVATE-TOKEN: <token>" "http://gdk.test:3000/api/v4/groups/<id>/merge_requests?state=opened&per_page=100"
  3. Disable the flag, wait a minute for the flag cache, repeat the call, and compare. gitaly_calls is higher by one FindCommit per merge request that reaches the conflict check, and detailed_merge_status values 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 like lazy_ref_exists? that loads each ref's target instead of true.
    • lazy_ref(ref): queues the ref in lazy_ref_target when the flag is on, and in master's lazy_ref_exists? when it is off. branch_exists?, tag_exists? and Gitlab::Git::RefPreloader.preload_refs_for_project go through it, so existence checks and branch head reads share one ListRefs call.
    • 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 with strong_memoize_attr. RefPreloader re-queues every collected ref on each branch_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_for sets the batched_branch_heads: true entity option for the three list endpoints (GET /merge_requests, GET /groups/:id/merge_requests, GET /projects/:id/merge_requests), not for view=simple.
  • API::Entities::MergeRequestBasic#detailed_merge_status passes options[:batched_branch_heads] to DetailedMergeStatusService, which adds batched_branch_heads: true to the check params only when it is set.
  • CheckConflictStatusService reads the source head from source_project.repository.batched_ref_target(source_branch_ref) when the param is set, and falls back to merge_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 around present has ended before detailed_merge_status runs. Entity options live on the entity objects, so they hold through that and through present_cached. Precedents: the issuable_metadata option in API::Entities::IssuableEntity, and Ci::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 ListRefs targets in Gitlab::SafeRequestStore and cleared them in three Repository expire hooks. Those hooks miss in-request branch moves: commit_files, merge_to_branch, ff_merge, cherry_pick and revert go through with_cache_hooks, which only fires after_create_branch, and rebase has no hook. Its opt-in also sat in the entity class, so it covered every MergeRequestBasic and MergeRequest render including write endpoints and MergeRequestAiEntity, and it only saved calls when the commits check had run first with ref_existence_check_gitaly on.
  • Rejected:
    • Gitlab::GitalyClient.allow_ref_name_caching around present: 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 changes source_branch_ref for every caller.
    • ListCommitsByRefName: one more RPC per repository, and the ListRefs result goes unused.

Staleness

  • The head comes from the same ListRefs snapshot that branch_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 ListRefs call and the render gives the same result as master, where FindCommit is 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_ref uses master's lazy_ref_exists?, batched_ref_target returns nil, and the conflict check uses source_branch_sha. The extra work is one memoized Feature.enabled? per repository, an unused option key and check param, and .present? on the existing boolean.
  • Flag on: every branch_exists? and tag_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 in spec/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, FindCommit 27 to 0.
    • GET /merge_requests (32): 30 to 3.
    • Project list (22), plain and present_cached paths: 21 to 2.
    • Every detailed_merge_status was equal, response bodies were byte-identical, and SQL counts were identical.
    • Flag evaluations on a project page of 40 merge requests: 1 per request.
  • A 70-scenario break matrix against master's CheckConflictStatusService and lazy_ref_exists? (fork, moved, deleted, prefix-only and unicode branches, importer sha override, missing repository, flag and ref_existence_check_gitaly states, 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_check and gitlab:permissions:validate pass 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.
  • FindCommit is 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_cached misses 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_at and merge_status, so it can serve a pre-push status until the refresh runs. Also master behaviour.

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.

Edited by Marc Shaw

Merge request reports

Loading
Loading