Merge branch 'introduce-pipeline-triggers' into 'master'

Improve pipeline triggers API

See merge request !9713

5 files changed, 183 insertions, 117 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 3399e2bb5f6..285cd2435ac 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -12,7 +12,6 @@ following locations:
 - [Branches](branches.md)
 - [Broadcast Messages](broadcast_messages.md)
 - [Builds](builds.md)
-- [Build Triggers](build_triggers.md)
 - [Build Variables](build_variables.md)
 - [Commits](commits.md)
 - [Deployments](deployments.md)
@@ -33,6 +32,7 @@ following locations:
 - [Notes](notes.md) (comments)
 - [Notification settings](notification_settings.md)
 - [Pipelines](pipelines.md)
+- [Pipeline Triggers](pipeline_triggers.md)
 - [Projects](projects.md) including setting Webhooks
 - [Project Access Requests](access_requests.md)
 - [Project Members](members.md)
diff --git a/doc/api/build_triggers.md b/doc/api/build_triggers.md
index 28befba69d6..20d924ab35e 100644
--- a/doc/api/build_triggers.md
+++ b/doc/api/build_triggers.md
@@ -1,108 +1 @@
-# Build triggers
-
-You can read more about [triggering builds through the API](../ci/triggers/README.md).
-
-## List project triggers
-
-Get a list of project's build triggers.
-
-```
-GET /projects/:id/triggers
-```
-
-| Attribute | Type    | required | Description         |
-|-----------|---------|----------|---------------------|
-| `id`      | integer | yes      | The ID of a project |
-
-```
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers"
-```
-
-```json
-[
-    {
-        "created_at": "2015-12-23T16:24:34.716Z",
-        "deleted_at": null,
-        "last_used": "2016-01-04T15:41:21.986Z",
-        "token": "fbdb730c2fbdb095a0862dbd8ab88b",
-        "updated_at": "2015-12-23T16:24:34.716Z"
-    },
-    {
-        "created_at": "2015-12-23T16:25:56.760Z",
-        "deleted_at": null,
-        "last_used": null,
-        "token": "7b9148c158980bbd9bcea92c17522d",
-        "updated_at": "2015-12-23T16:25:56.760Z"
-    }
-]
-```
-
-## Get trigger details
-
-Get details of project's build trigger.
-
-```
-GET /projects/:id/triggers/:token
-```
-
-| Attribute | Type    | required | Description              |
-|-----------|---------|----------|--------------------------|
-| `id`      | integer | yes      | The ID of a project      |
-| `token`   | string  | yes      | The `token` of a trigger |
-
-```
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/7b9148c158980bbd9bcea92c17522d"
-```
-
-```json
-{
-    "created_at": "2015-12-23T16:25:56.760Z",
-    "deleted_at": null,
-    "last_used": null,
-    "token": "7b9148c158980bbd9bcea92c17522d",
-    "updated_at": "2015-12-23T16:25:56.760Z"
-}
-```
-
-## Create a project trigger
-
-Create a build trigger for a project.
-
-```
-POST /projects/:id/triggers
-```
-
-| Attribute | Type    | required | Description              |
-|-----------|---------|----------|--------------------------|
-| `id`      | integer | yes      | The ID of a project      |
-
-```
-curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers"
-```
-
-```json
-{
-    "created_at": "2016-01-07T09:53:58.235Z",
-    "deleted_at": null,
-    "last_used": null,
-    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
-    "updated_at": "2016-01-07T09:53:58.235Z"
-}
-```
-
-## Remove a project trigger
-
-Remove a project's build trigger.
-
-```
-DELETE /projects/:id/triggers/:token
-```
-
-| Attribute | Type    | required | Description              |
-|-----------|---------|----------|--------------------------|
-| `id`      | integer | yes      | The ID of a project      |
-| `token`   | string  | yes      | The `token` of a trigger |
-
-```
-curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/7b9148c158980bbd9bcea92c17522d"
-```
+This document was moved to [Pipeline Triggers](pipeline_triggers.md).
diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md
new file mode 100644
index 00000000000..fdb41a1d615
--- /dev/null
+++ b/doc/api/pipeline_triggers.md
@@ -0,0 +1,170 @@
+# Pipeline triggers
+
+You can read more about [triggering pipelines through the API](../ci/triggers/README.md).
+
+## List project triggers
+
+Get a list of project's build triggers.
+
+```
+GET /projects/:id/triggers
+```
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| `id`      | integer | yes      | The ID of a project |
+
+```
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers"
+```
+
+```json
+[
+    {
+        "id": 10,
+        "description": "my trigger",
+        "created_at": "2016-01-07T09:53:58.235Z",
+        "deleted_at": null,
+        "last_used": null,
+        "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
+        "updated_at": "2016-01-07T09:53:58.235Z",
+        "owner": null
+    }
+]
+```
+
+## Get trigger details
+
+Get details of project's build trigger.
+
+```
+GET /projects/:id/triggers/:trigger_id
+```
+
+| Attribute | Type    | required | Description              |
+|-----------|---------|----------|--------------------------|
+| `id`      | integer | yes      | The ID of a project      |
+| `token`   | string  | yes      | The `token` of a trigger |
+
+```
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
+```
+
+```json
+{
+    "id": 10,
+    "description": "my trigger",
+    "created_at": "2016-01-07T09:53:58.235Z",
+    "deleted_at": null,
+    "last_used": null,
+    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
+    "updated_at": "2016-01-07T09:53:58.235Z",
+    "owner": null
+}
+```
+
+## Create a project trigger
+
+Create a trigger for a project.
+
+```
+POST /projects/:id/triggers
+```
+
+| Attribute     | Type    | required | Description              |
+|---------------|---------|----------|--------------------------|
+| `id`          | integer | yes      | The ID of a project      |
+| `description` | string  | yes      | The trigger name         |
+
+```
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers"
+```
+
+```json
+{
+    "id": 10,
+    "description": "my trigger",
+    "created_at": "2016-01-07T09:53:58.235Z",
+    "deleted_at": null,
+    "last_used": null,
+    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
+    "updated_at": "2016-01-07T09:53:58.235Z",
+    "owner": null
+}
+```
+
+## Update a project trigger
+
+Update a trigger for a project.
+
+```
+PUT /projects/:id/triggers/:trigger_id
+```
+
+| Attribute     | Type    | required | Description              |
+|---------------|---------|----------|--------------------------|
+| `trigger_id`  | integer | yes      | The trigger id           |
+| `description` | string  | no       | The trigger name         |
+
+```
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10"
+```
+
+```json
+{
+    "id": 10,
+    "description": "my trigger",
+    "created_at": "2016-01-07T09:53:58.235Z",
+    "deleted_at": null,
+    "last_used": null,
+    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
+    "updated_at": "2016-01-07T09:53:58.235Z",
+    "owner": null
+}
+```
+
+## Take ownership of a project trigger
+
+Update an owner of a project trigger.
+
+```
+POST /projects/:id/triggers/:trigger_id/take_ownership
+```
+
+| Attribute     | Type    | required | Description              |
+|---------------|---------|----------|--------------------------|
+| `trigger_id`  | integer | yes      | The trigger id           |
+
+```
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/10/take_ownership"
+```
+
+```json
+{
+    "id": 10,
+    "description": "my trigger",
+    "created_at": "2016-01-07T09:53:58.235Z",
+    "deleted_at": null,
+    "last_used": null,
+    "token": "6d056f63e50fe6f8c5f8f4aa10edb7",
+    "updated_at": "2016-01-07T09:53:58.235Z",
+    "owner": null
+}
+```
+
+## Remove a project trigger
+
+Remove a project's build trigger.
+
+```
+DELETE /projects/:id/triggers/:trigger_id
+```
+
+| Attribute      | Type    | required | Description              |
+|----------------|---------|----------|--------------------------|
+| `id`           | integer | yes      | The ID of a project      |
+| `trigger_id`   | integer | yes      | The trigger id           |
+
+```
+curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
+```
diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md
index 39dc6d98e7b..67ee2b69c3f 100644
--- a/doc/api/v3_to_v4.md
+++ b/doc/api/v3_to_v4.md
@@ -59,3 +59,6 @@ changes are in V4:
 - Return 202 with JSON body on async removals on V4 API (DELETE `/projects/:id/repository/merged_branches` and DELETE `/projects/:id`) [!9449](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9449)
 - `projects/:id/milestones?iid[]=x&iid[]=y` array filter has been renamed to `iids` [!9096](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9096)
 - Return basic info about pipeline in `GET /projects/:id/pipelines` [!8875](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8875)
+- Rename Build Triggers to be Pipeline Triggers API [!9713](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9713)
+  - `POST /projects/:id/trigger/builds` to `POST /projects/:id/trigger/pipeline`
+  - Require description when creating a new trigger `POST /projects/:id/triggers`
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md
index 1ad9621c8a0..ccaee33dc92 100644
--- a/doc/ci/triggers/README.md
+++ b/doc/ci/triggers/README.md
@@ -36,7 +36,7 @@ it will not trigger a job.
 To trigger a job you need to send a `POST` request to GitLab's API endpoint:
 
 ```
-POST /projects/:id/trigger/builds
+POST /projects/:id/trigger/pipeline
 ```
 
 The required parameters are the trigger's `token` and the Git `ref` on which
@@ -71,7 +71,7 @@ To trigger a job from webhook of another project you need to add the following
 webhook url for Push and Tag push events:
 
 ```
-https://gitlab.example.com/api/v4/projects/:id/ref/:ref/trigger/builds?token=TOKEN
+https://gitlab.example.com/api/v4/projects/:id/ref/:ref/trigger/pipeline?token=TOKEN
 ```
 
 > **Note**:
@@ -105,7 +105,7 @@ Using cURL you can trigger a rebuild with minimal effort, for example:
 curl --request POST \
      --form token=TOKEN \
      --form ref=master \
-     https://gitlab.example.com/api/v4/projects/9/trigger/builds
+     https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
 ```
 
 In this case, the project with ID `9` will get rebuilt on `master` branch.
@@ -114,7 +114,7 @@ Alternatively, you can pass the `token` and `ref` arguments in the query string:
 
 ```bash
 curl --request POST \
-    "https://gitlab.example.com/api/v4/projects/9/trigger/builds?token=TOKEN&ref=master"
+    "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master"
 ```
 
 ### Triggering a job within `.gitlab-ci.yml`
@@ -128,7 +128,7 @@ need to add in project's A `.gitlab-ci.yml`:
 build_docs:
   stage: deploy
   script:
-  - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/builds"
+  - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
   only:
   - tags
 ```
@@ -187,7 +187,7 @@ curl --request POST \
   --form token=TOKEN \
   --form ref=master \
   --form "variables[UPLOAD_TO_S3]=true" \
-  https://gitlab.example.com/api/v4/projects/9/trigger/builds
+  https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
 ```
 
 ### Using webhook to trigger job
@@ -195,7 +195,7 @@ curl --request POST \
 You can add the following webhook to another project in order to trigger a job:
 
 ```
-https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/builds?token=TOKEN&variables[UPLOAD_TO_S3]=true
+https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN&variables[UPLOAD_TO_S3]=true
 ```
 
 ### Using cron to trigger nightly jobs
@@ -205,7 +205,7 @@ in conjunction with cron. The example below triggers a job on the `master`
 branch of project with ID `9` every night at `00:30`:
 
 ```bash
-30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/builds
+30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
 ```
 
 [ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229