Merge branch 'merge-if-green' into 'master'

Merge when build succeeds

### What does this MR do?
Adds a button to a MR when the build/ci is running so it can be merged when/if the build is successfull.

### Are there points in the code the reviewer needs to double check?
English spelling and whether or not the grammer is correct.

### Why was this MR needed?
When you expect its all good, and don't want to revisit the current MR it can be accepted allready.

### What are the relevant issue numbers / Feature requests?
Fixes #2640 -- although `Merge if green` is replaced with `Merge when the build succeeds` the general idea is the same.

### Screenshots (if relevant)
![Screenshot_from_2015-12-07_10-34-39](/uploads/b90b558b6ad6c8266bc9c96120d86f96/Screenshot_from_2015-12-07_10-34-39.png)

![Screenshot_from_2015-11-02_17-26-56](/uploads/9f52f56e3c5e9ec63cb8f42978c92a52/Screenshot_from_2015-11-02_17-26-56.png)
![Screenshot_from_2015-11-02_17-27-03](/uploads/119fc18c9b15ff73dc38010ac5b6244a/Screenshot_from_2015-11-02_17-27-03.png)

![Screenshot_from_2015-12-03_10-08-14](/uploads/bad7b35c7d129981d43631877c958be0/Screenshot_from_2015-12-03_10-08-14.png)

![Screenshot_from_2015-11-02_17-27-16](/uploads/b616d750a16cc11ba72f2ca84213515e/Screenshot_from_2015-11-02_17-27-16.png)

### Further considerations
What if there are minor things needed solving, e.g. Rubocop, the current implementation will reset the approved status of the MR. It might be a consideration keep the approval for team member, or even guests. This would require an extra option in the Admin screen, though might add extra value.

#### TODO
- [x] Docs
- [x] Specs

/cc @DouweM @rspeicher

See merge request !1729

5 files changed, 67 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/README.md b/doc/workflow/README.md
index a6b4d951188..d2642495c9a 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -17,4 +17,5 @@
 - [Milestones](milestones.md)
 - [Merge Requests](merge_requests.md)
 - ["Work In Progress" Merge Requests](wip_merge_requests.md)
+- [Merge When Build Succeeds](merge_when_build_succeeds.md)
 - [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md)
diff --git a/doc/workflow/merge_when_build_succeeds.md b/doc/workflow/merge_when_build_succeeds.md
new file mode 100644
index 00000000000..75e1fdff2b2
--- /dev/null
+++ b/doc/workflow/merge_when_build_succeeds.md
@@ -0,0 +1,15 @@
+# Merge When Build Succeeds
+
+When reviewing a merge request that looks ready to merge but still has one or more CI builds running, you can set it to be merged automatically when all builds succeed. This way, you don't have to wait for the builds to finish and remember to merge the request manually.
+
+![Enable](merge_when_build_succeeds/enable.png)
+
+When you hit the "Merge When Build Succeeds" button, the status of the merge request will be updated to represent the impending merge. If you cannot wait for the build to succeed and want to merge immediately, this option is available in the dropdown menu on the right of the main button.
+
+Both team developers and the author of the merge request have the option to cancel the automatic merge if they find a reason why it shouldn't be merged after all.
+
+![Status](merge_when_build_succeeds/status.png)
+
+When the build succeeds, the merge request will automatically be merged. When the build fails, the author gets a chance to retry any failed builds, or to push new commits to fix the failure.
+
+When the builds are retried and succeed on the second try, the merge request will automatically be merged after all. When the merge request is updated with new commits, the automatic merge is automatically canceled to allow the new changes to be reviewed.
diff --git a/doc/workflow/merge_when_build_succeeds/enable.png b/doc/workflow/merge_when_build_succeeds/enable.png
new file mode 100644
index 00000000000..633efa1246f
--- /dev/null
+++ b/doc/workflow/merge_when_build_succeeds/enable.png
diff --git a/doc/workflow/merge_when_build_succeeds/status.png b/doc/workflow/merge_when_build_succeeds/status.png
new file mode 100644
index 00000000000..c856c7d14dc
--- /dev/null
+++ b/doc/workflow/merge_when_build_succeeds/status.png