Add API support for refreshing merge ref path

Add a merge_requests/:iid/merge_to_ref API which make
use of the groundwork to write merge results into
refs/merge-requests/:iid/merge.

1 files changed, 34 insertions, 0 deletions

diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index e176cdffc5f..ed4b6281acc 100644
--- a/doc/api/merge_requests.md
+++ b/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`