## Problem Statement When a rebase operation fails in a merge request, in most scenarios users receive a generic error message: **"Rebase failed: Rebase locally, resolve all conflicts, then push the branch. Try again."** There are exceptions to this - it looks like we surface customized messages for pre-receive hook errors (https://gitlab.com/gitlab-org/frontend/playground/markrian/gitlab-shallow-copy/-/blame/master/app/services/merge_requests/rebase_service.rb). But the generic message is unhelpful because it doesn't indicate the actual cause of the failure, and assumes the failure is due to a rebase conflict. Different failure scenarios require different actions from the user: - Push rule validation failures require fixing commit metadata - Gitaly concurrency limits require retrying later or contacting an administrator - Actual merge conflicts require local resolution Currently, all these scenarios show the same generic message, leaving users confused about what went wrong and how to fix it. ## Scenarios ### Scenario 1: Push Rule Validation Failure **Context**: When a project has push rules configured (e.g., requiring commit author/committer email addresses to match a regex pattern as documented in https://docs.gitlab.com/user/project/repository/push_rules/#verify-users), a rebase operation can fail if the rebased commits don't meet these validation rules. **Steps to Reproduce**: 1. Create a project with push rules enabled: - Go to **Settings** > **Repository** > **Push rules** - Enable **Commit author's email** rule with a regex pattern (e.g., `.*@company\.com$`) - Save push rules 2. Create a merge request with commits from an email that doesn't match the regex: - Create a feature branch with a commit authored by `user@personal.com` - Push the branch and create a merge request 3. Update the target branch to trigger the need for a rebase: - Make a commit to the target branch - The merge request will show as "behind target branch" 4. Click the **Rebase** button in the merge request widget **Current Behavior**: Generic error message "Rebase failed: Rebase locally, resolve all conflicts, then push the branch. Try again." **Expected Behavior**: Error message should indicate the push rule validation failure, e.g., "Rebase failed: Commit author email does not match the required pattern. Please ensure all commits are authored by an email matching: `.*@company\.com$`" --- ### Scenario 2: Gitaly Concurrency Limit Hit **Context**: Gitaly's RPC concurrency limiting feature (as documented in https://docs.gitlab.com/administration/gitaly/concurrency_limiting/#limit-rpc-concurrency), can be set up to limit concurrent requests to the `/gitaly.OperationService/UserRebaseConfirmable` RPC, which limits concurrent rebases per repository. **Steps to Reproduce** (Self-Managed GitLab): 1. Configure Gitaly concurrency limits: - Edit `/etc/gitlab/gitlab.rb` or your Gitaly configuration - Set a low concurrency limit for `UserRebaseConfirmable` RPC (e.g., 2 concurrent requests) - Restart Gitaly 2. Trigger multiple concurrent rebase operations via the API. Here's a sample script that uses `python-gitlab` to achieve this: [gitlab_rebase_setup.py](/uploads/d2be664d233a1e1e22f6456a46ca48fb/gitlab_rebase_setup.py) ``` python gitlab_rebase_setup.py --num-branches 5 --token <your-token> ``` 3. Observe the error: - Some rebase operations will fail with the generic error message **Current Behavior**: Generic error message "Rebase failed: Rebase locally, resolve all conflicts, then push the branch. Try again." **Expected Behavior**: Error message should indicate the concurrency limit was hit, e.g., "Rebase failed: The system is currently processing too many rebase operations. Please try again in a few moments." For self-managed instances, it could also suggest: "If this persists, contact your GitLab administrator to review Gitaly concurrency limits." --- ## Example errors - "Rebase failed due to push rule validation. Your commits must be authored by an email matching the pattern: `.*@company\.com`. [Learn more about push rules](link)" - "Rebase failed: The system is currently processing many rebase operations. Please try again in a few moments." - "Rebase failed: You don't have permission to rebase this merge request. Contact a project maintainer." --- ## Related Issues This feature request is related to the broader effort to improve merge request error messaging tracked in [#584764](https://gitlab.com/gitlab-org/gitlab/-/work_items/584764).