Add latest changes from gitlab-org/gitlab@master

1 files changed, 80 insertions, 0 deletions

diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md
new file mode 100644
index 00000000000..7fff09474df
--- /dev/null
+++ b/doc/api/merge_trains.md
@@ -0,0 +1,80 @@
+# Merge Trains API **(PREMIUM)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36146) in GitLab 12.9.
+> - Using this API you can consume GitLab's [Merge Train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) entries.
+
+Every API call to merge trains must be authenticated with Developer or higher [permissions](link-to-permissions-doc).
+
+If a user is not a member of a project and the project is private, a `GET` request on that project will result to a `404` status code.
+
+If Merge Trains is not available for the project, a `403` status code will return.
+
+## Merge Trains API pagination
+
+By default, `GET` requests return 20 results at a time because the API results
+are paginated.
+
+Read more on [pagination](README.md#pagination).
+
+## List Merge Trains for a project
+
+Get all Merge Trains of the requested project:
+
+```txt
+GET /projects/:id/merge_trains
+GET /projects/:id/merge_trains?scope=complete
+```
+
+| Attribute           | Type             | Required   | Description                                                                                                                 |
+| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding).                                            |
+| `scope`             | string           | no         | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). |
+| `sort`              | string           | no         | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc`.                                                     |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/merge_trains
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 110,
+    "merge_request": {
+      "id": 126,
+      "iid": 59,
+      "project_id": 20,
+      "title": "Test MR 1580978354",
+      "description": "",
+      "state": "merged",
+      "created_at": "2020-02-06T08:39:14.883Z",
+      "updated_at": "2020-02-06T08:40:57.038Z",
+      "web_url": "http://local.gitlab.test:8181/root/merge-train-race-condition/-/merge_requests/59"
+    },
+    "user": {
+      "id": 1,
+      "name": "Administrator",
+      "username": "root",
+      "state": "active",
+      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+      "web_url": "http://local.gitlab.test:8181/root"
+    },
+    "pipeline": {
+      "id": 246,
+      "sha": "bcc17a8ffd51be1afe45605e714085df28b80b13",
+      "ref": "refs/merge-requests/59/train",
+      "status": "success",
+      "created_at": "2020-02-06T08:40:42.410Z",
+      "updated_at": "2020-02-06T08:40:46.912Z",
+      "web_url": "http://local.gitlab.test:8181/root/merge-train-race-condition/pipelines/246"
+    },
+    "created_at": "2020-02-06T08:39:47.217Z",
+    "updated_at": "2020-02-06T08:40:57.720Z",
+    "target_branch": "feature-1580973432",
+    "status": "merged",
+    "merged_at": "2020-02-06T08:40:57.719Z",
+    "duration": 70
+  }
+]
+```