## Problem When a merge request is dropped from a merge train because of a conflict, the system note and `merge_request.merge_error` name the failure but not which files conflict. https://gitlab.com/gitlab-org/gitlab/-/merge_requests/251122 already made the note readable: it strips the gRPC status-code prefix and frames the reason. But file names still cannot appear, because they only travel in the `UserMergeToRefError` detail added by https://gitlab.com/gitlab-org/gitaly/-/merge_requests/9118, and nothing on the Rails side decodes it for this RPC. `Gitlab::GitalyClient::OperationService#user_merge_to_ref` (`lib/gitlab/gitaly_client/operation_service.rb`) has no `rescue GRPC::BadStatus` at all. The error falls through `Gitlab::Git::WrapsGitalyErrors#handle_error`, whose `handle_detailed_error` has no `Gitaly::MergeConflictError` branch, and ends up as a generic `Gitlab::Git::CommandError` with no file information. **Blocked by:** a `gitaly` gem release containing `Gitaly::UserMergeToRefError`. The Gitaly side is merged; no published gem version contains the message yet, so the first usable version is expected from the 19.4 release cycle. Only the gem update is blocked on that; the Rails-side rescue block itself degrades safely and can merge independently. ## Proposal 1. Update the `gitaly` gem to the first release that contains `Gitaly::UserMergeToRefError`. The `Gemfile` constraint `~> 19.2` already permits any `19.x`, so this is likely a `Gemfile.lock`-only change via `bundle update gitaly`. Until that release exists, `GitalyClient.decode_detailed_error` resolves the type via `Gitaly.const_get` and rescues `NameError` to `nil`, so nothing breaks either way. 2. Add a `rescue GRPC::BadStatus` block to `#user_merge_to_ref`, modelled on `#user_revert`. On `:merge_conflict`, raise `Gitlab::Git::CommandError` with the existing message as a prefix plus an additive suffix naming the conflicting files. On anything else, re-raise unchanged. 3. Keep this backwards compatible: - Keep the exception class as `Gitlab::Git::CommandError`. Both callers, `MergeRequests::CreateRefService#safe_gitaly_operation` and `MergeRequests::MergeToRefService#extracted_merge_to_ref`, rescue by class and forward only `error.message`. Class and message-prefix stability is the whole contract. - `conflicting_files` is `repeated bytes` (Git paths are not guaranteed UTF-8): encode it via `Gitlab::EncodingHelper` before interpolating. Otherwise persisting `merge_error` or building the system note could fail on invalid UTF-8, a failure path that does not exist today. - Cap the list (for example, first 10 files plus "and N more"). The message flows into a database column and a system note. - Degradation works in both directions: a Gitaly server without the change attaches no detail (`nil`, re-raise, identical to today), an old gem cannot decode the type (`NameError`, `nil`, identical to today). The Rails change can merge before the new Gitaly is deployed. 4. Update `doc/ci/pipelines/merge_trains.md`, troubleshooting section "Merge request dropped from the merge train", to mention that the reason can include the conflicting file names. Hint: No change needed in the merge-train layer. `MergeTrains::RefreshMergeRequestService#pipeline_creation_error` already passes richer message text through into the system note. ## Prior art / product note No RPC's `MergeConflictError` payload is consumed in Rails today. `#user_revert` decodes it and discards the payload, raising `Gitlab::Git::Repository::CreateTreeError, 'CONFLICT'`. `#user_squash` carries an explicit comment stating it deliberately does not use the file list, for backwards compatibility. Surfacing file names here would be the first case that does, so this is a deliberate product-visible change, not just plumbing. ## References - https://gitlab.com/gitlab-org/gitaly/-/merge_requests/9118 - https://gitlab.com/gitlab-org/gitaly/-/merge_requests/9118#note_3723068018 - https://gitlab.com/gitlab-org/gitaly/-/issues/7330 - https://gitlab.com/gitlab-org/gitlab/-/issues/394901 - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/251122 ## Acceptance criteria - [ ] `gitaly` gem is updated to a version providing `Gitaly::UserMergeToRefError` (first expected from the 19.4 release cycle). - [x] `Gitlab::GitalyClient::OperationService#user_merge_to_ref` decodes a `:merge_conflict` detailed error and appends the conflicting file names (capped, with an "and N more" suffix) to the existing `Gitlab::Git::CommandError` message. - [x] Non-UTF-8 file paths in `conflicting_files` are encoded via `Gitlab::EncodingHelper` and do not raise when persisted to `merge_request.merge_error` or rendered in a system note. - [x] When no detailed error is attached (older Gitaly) or the gem cannot decode the type (older gem), behavior is unchanged from today, verified by a spec covering both cases. - [ ] A merge-train merge conflict on `UserMergeToRef` produces a system note that names the conflicting files. - [x] `doc/ci/pipelines/merge_trains.md` documents that the drop reason can include conflicting file names.