Merge branch 'osw-merge-refs-refreshing-api' into 'master'

API support for MR merge to temporary merge ref path

Closes #57252

See merge request gitlab-org/gitlab-ce!24918

changelogs/unreleased/osw-merge-refs-refreshing-api.yml

+---
+title: API support for MR merge to temporary merge ref path
+merge_request: 24918
+author:
+type: added

doc/api/merge_requests.md

@@ -1101,6 +1101,40 @@ Parameters:
 }
 ```
 
+## Merge to default merge ref path
+
+Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` 
+ref, of the target project repository. This ref will have the state the target branch would have if
+a regular merge action was taken.
+
+This is not a regular merge action given it doesn't change the merge request state in any manner.
+
+This ref (`refs/merge-requests/:iid/merge`) is **always** overwritten when submitting
+requests to this API, so none of its state is kept or used in the process.
+
+If the merge request has conflicts, is empty or already merged,
+you'll get a `400` and a descriptive error message. If you don't have permissions to do so, 
+you'll get a `403`.
+
+It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in
+case of `200`.
+
+```
+PUT /projects/:id/merge_requests/:merge_request_iid/merge_to_ref
+```
+
+Parameters:
+
+- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
+- `merge_request_iid` (required)            - Internal ID of MR
+- `merge_commit_message` (optional)         - Custom merge commit message
+
+```json
+{
+  "commit_id": "854a3a7a17acbcc0bbbea170986df1eb60435f34"
+}
+```
+
 ## Cancel Merge When Pipeline Succeeds
 
 If you don't have permissions to accept this merge request - you'll get a `401`

lib/api/merge_requests.rb

@@ -388,6 +388,31 @@ module API
         present merge_request, with: Entities::MergeRequest, current_user: current_user, project: user_project
       end
 
+      desc 'Merge a merge request to its default temporary merge ref path'
+      params do
+        optional :merge_commit_message, type: String, desc: 'Custom merge commit message'
+      end
+      put ':id/merge_requests/:merge_request_iid/merge_to_ref' do
+        merge_request = find_project_merge_request(params[:merge_request_iid])
+
+        authorize! :admin_merge_request, user_project
+
+        merge_params = {
+          commit_message: params[:merge_commit_message]
+        }
+
+        result = ::MergeRequests::MergeToRefService
+          .new(merge_request.target_project, current_user, merge_params)
+          .execute(merge_request)
+
+        if result[:status] == :success
+          present result.slice(:commit_id), 200
+        else
+          http_status = result[:http_status] || 400
+          render_api_error!(result[:message], http_status)
+        end
+      end
+
       desc 'Cancel merge if "Merge When Pipeline Succeeds" is enabled' do
         success Entities::MergeRequest
       end

spec/requests/api/merge_requests_spec.rb

@@ -1013,6 +1013,67 @@ describe API::MergeRequests do
     end
   end
 
+  describe "PUT /projects/:id/merge_requests/:merge_request_iid/merge_to_ref" do
+    let(:pipeline) { create(:ci_pipeline_without_jobs) }
+    let(:url) do
+      "/projects/#{project.id}/merge_requests/#{merge_request.iid}/merge_to_ref"
+    end
+
+    it 'returns the generated ID from the merge service in case of success' do
+      put api(url, user), params: { merge_commit_message: 'Custom message' }
+
+      commit = project.commit(json_response['commit_id'])
+
+      expect(response).to have_gitlab_http_status(200)
+      expect(json_response['commit_id']).to be_present
+      expect(commit.message).to eq('Custom message')
+    end
+
+    it "returns 400 if branch can't be merged" do
+      merge_request.update!(state: 'merged')
+
+      put api(url, user)
+
+      expect(response).to have_gitlab_http_status(400)
+      expect(json_response['message'])
+        .to eq("Merge request is not mergeable to #{merge_request.merge_ref_path}")
+    end
+
+    it 'returns 403 if user has no permissions to merge to the ref' do
+      user2 = create(:user)
+      project.add_reporter(user2)
+
+      put api(url, user2)
+
+      expect(response).to have_gitlab_http_status(403)
+      expect(json_response['message']).to eq('403 Forbidden')
+    end
+
+    it 'returns 404 for an invalid merge request IID' do
+      put api("/projects/#{project.id}/merge_requests/12345/merge_to_ref", user)
+
+      expect(response).to have_gitlab_http_status(404)
+    end
+
+    it "returns 404 if the merge request id is used instead of iid" do
+      put api("/projects/#{project.id}/merge_requests/#{merge_request.id}/merge", user)
+
+      expect(response).to have_gitlab_http_status(404)
+    end
+
+    it "returns 400 when merge method is not supported" do
+      merge_request.project.update!(merge_method: 'ff')
+
+      put api(url, user)
+
+      expected_error =
+        'Fast-forward to refs/merge-requests/1/merge is currently not supported.'
+
+      expect(response).to have_gitlab_http_status(400)
+      expect(json_response['message']).to eq(expected_error)
+    end
+  end
+
   describe "PUT /projects/:id/merge_requests/:merge_request_iid" do
     context "to close a MR" do
       it "returns merge_request" do