4 files changed, 71 insertions, 3 deletions
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 82f2cef969f..366a1f8abec 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -335,9 +335,57 @@ PUT /projects/:id/merge_request/:merge_request_id/merge
 
 Parameters:
 
-- `id` (required)                   - The ID of a project
-- `merge_request_id` (required)     - ID of MR
-- `merge_commit_message` (optional) - Custom merge commit message
+- `id` (required)                           - The ID of a project
+- `merge_request_id` (required)             - ID of MR
+- `merge_commit_message` (optional)         - Custom merge commit message
+- `should_remove_source_branch` (optional)  - if `true` removes the source branch
+- `merged_when_build_succeeds` (optional)    - if `true` the MR is merge when the build succeeds
+
+```json
+{
+  "id": 1,
+  "target_branch": "master",
+  "source_branch": "test1",
+  "project_id": 3,
+  "title": "test1",
+  "state": "merged",
+  "upvotes": 0,
+  "downvotes": 0,
+  "author": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@example.com",
+    "name": "Administrator",
+    "state": "active",
+    "created_at": "2012-04-29T08:46:00Z"
+  },
+  "assignee": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@example.com",
+    "name": "Administrator",
+    "state": "active",
+    "created_at": "2012-04-29T08:46:00Z"
+  }
+}
+```
+
+## Cancel Merge When Build Succeeds
+
+If successful you'll get `200 OK`.
+
+If you don't have permissions to accept this merge request - you'll get a 401
+
+If the merge request is already merged or closed - you get 405 and error message 'Method Not Allowed'
+
+In case the merge request is not set to be merged when the build succeeds, you'll also get a 406 error.
+```
+PUT /projects/:id/merge_request/:merge_request_id/cancel_merge_when_build_succeeds
+```
+Parameters:
+
+- `id` (required)                           - The ID of a project
+- `merge_request_id` (required)             - ID of MR
 
 ```json
 {
diff --git a/doc/workflow/merge_requests/disable_merge_when_build_succeeds.png b/doc/workflow/merge_requests/disable_merge_when_build_succeeds.png
new file mode 100644
index 00000000000..a45a4890b62
--- /dev/null
+++ b/doc/workflow/merge_requests/disable_merge_when_build_succeeds.png
diff --git a/doc/workflow/merge_requests/enable_merge_when_build_succeeds.png b/doc/workflow/merge_requests/enable_merge_when_build_succeeds.png
new file mode 100644
index 00000000000..62a46c9508b
--- /dev/null
+++ b/doc/workflow/merge_requests/enable_merge_when_build_succeeds.png
diff --git a/doc/workflow/merge_when_build_succeeds.md b/doc/workflow/merge_when_build_succeeds.md
new file mode 100644
index 00000000000..9bf6ddcc569
--- /dev/null
+++ b/doc/workflow/merge_when_build_succeeds.md
@@ -0,0 +1,20 @@
+# Merge When Build Succeeds
+
+Select a Merge Request to be merged if the build succeeds so the user does not have to wait for the build to finish and revisit the Merge Request to merge it after the build is done.
+
+## Enabling for a Merge Request
+
+Given an active build for a Merge Request, thus pending or running, a `Merge When Build Succeeds` button will appear to any user which can merge it. Once clicked, it ensures this merge request is merged when the build is successful.
+When clicking the button, the merge parameters are also saved to allow the merge user to edit the commit message and remove the source branch if he can remove that branch.
+
+When this feature is enabled, a message will appear to notify other users. Also a note is posted on the thread.
+
+![Enable Merge When Build Succceeds](merge_requests/enable_merge_when_build_succeeds.png)
+
+## Canceling
+
+The automatic merge can be disabled by clicking the `Cancel Automatic Merge` button, or when a new commit is added to the Merge Request. In the former case a note is posted. In the latter case a user able to merge can enable the feature again.
+
+![Disable the automatic merge](merge_requests/disable_merge_when_build_succeeds.png)
+
+A failed build does not reset the automatic build so a build can be retried.