Merge branch 'docs-api-merge-2' into 'master'

Docs: Merge 5 api docs from EE to CE See merge request gitlab-org/gitlab-ce!28633

Merge branch 'docs-api-merge-2' into 'master'
Docs: Merge 5 api docs from EE to CE See merge request gitlab-org/gitlab-ce!28633
33537616 · Achilleas Pipinellis · 3fd99b4e · d46dca74 · 33537616 · 33537616
Commit 33537616 authored Jun 06, 2019 by Achilleas Pipinellis
5 changed files
--- a/doc/api/README.md
+++ b/doc/api/README.md
--- a/doc/api/jobs.md
+++ b/doc/api/jobs.md
@@ -346,30 +346,58 @@ Example of response
 > **Notes**:
 >
 > - [Introduced][ce-2893] in GitLab 8.5.
+> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
+>   in [GitLab Premium][ee] 9.5.
-Get job artifacts of a project.
+Get the job's artifacts zipped archive of a project.
 ```
 GET /projects/:id/jobs/:job_id/artifacts
 ```
 | Attribute   | Type           | Required | Description                                                                                                                                     |
-|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
+|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
 | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                |
 | `job_id`    | integer        | yes      | ID of a job.                                                                                                                                |
+| `job_token` **[PREMIUM]** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
-Example requests:
+Example request using the `PRIVATE-TOKEN` header:
 ```sh
-curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts"
+curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"
 ```
+To use this in a [`script` definition](../ci/yaml/README.md#script) inside
+`.gitlab-ci.yml` **[PREMIUM]**, you can use either:
+- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
+  For example, the following job will download the artifacts of the job with ID
+  `42`. Note that the command is wrapped into single quotes since it contains a
+  colon (`:`):
+  ```yaml
+  artifact_download:
+    stage: test
+    script:
+      - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"'
+  ```
+- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable.
+  For example, the following job will download the artifacts of the job with ID `42`:
+  ```yaml
+  artifact_download:
+    stage: test
+    script:
+      - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"'
+  ```
 Possible response status codes:
 | Status    | Description                     |
 |-----------|---------------------------------|
-| 200       | Serves the artifacts file       |
+| 200       | Serves the artifacts file.      |
-| 404       | Build not found or no artifacts |
+| 404       | Build not found or no artifacts.|
 [ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893
@@ -378,9 +406,13 @@ Possible response status codes:
 > **Notes**:
 >
 > - [Introduced][ce-5347] in GitLab 8.10.
+> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
+>   in [GitLab Premium][ee] 9.5.
-Download the artifacts archive from the given reference name and job provided the
+Download the artifacts zipped archive from the given reference name and job,
-job finished successfully.
+provided the job finished successfully. This is the same as
+[getting the job's artifacts](#get-job-artifacts), but by defining the job's
+name instead of its ID.
 ```
 GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
@@ -389,23 +421,50 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
 Parameters
 | Attribute   | Type           | Required | Description                                                                                                                                     |
-|------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
+|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
 | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                |
 | `ref_name`  | string         | yes      | Branch or tag name in repository. HEAD or SHA references are not supported.                                                                     |
 | `job`       | string         | yes      | The name of the job.                                                                                                                            |
+| `job_token` **[PREMIUM]** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
-Example requests:
+Example request using the `PRIVATE-TOKEN` header:
 ```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
 ```
+To use this in a [`script` definition](../ci/yaml/README.md#script) inside
+`.gitlab-ci.yml` **[PREMIUM]**, you can use either:
+- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
+  For example, the following job will download the artifacts of the `test` job
+  of the `master` branch. Note that the command is wrapped into single quotes
+  since it contains a colon (`:`):
+  ```yaml
+  artifact_download:
+    stage: test
+    script:
+      - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test"'
+  ```
+- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable.
+  For example, the following job will download the artifacts of the `test` job
+  of the `master` branch:
+  ```yaml
+  artifact_download:
+    stage: test
+    script:
+      - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"'
+  ```
 Possible response status codes:
 | Status    | Description                     |
 |-----------|---------------------------------|
-| 200       | Serves the artifacts file       |
+| 200       | Serves the artifacts file.      |
-| 404       | Build not found or no artifacts |
+| 404       | Build not found or no artifacts.|
 [ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347
@@ -414,7 +473,7 @@ Possible response status codes:
 > Introduced in GitLab 10.0
 Download a single artifact file from a job with a specified ID from within
-the job's artifacts archive. The file is extracted from the archive and
+the job's artifacts zipped archive. The file is extracted from the archive and
 streamed to the client.
 ```
@@ -783,3 +842,7 @@ Example of response
  "user": null
 }
 ```
+[ee]: https://about.gitlab.com/pricing/
+[ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346
+[triggers]: ../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium
--- a/doc/api/project_clusters.md
+++ b/doc/api/project_clusters.md
@@ -167,6 +167,7 @@ Parameters:
 | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
 | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
 | `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
+| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **[PREMIUM]** |
 Example request:
@@ -256,6 +257,7 @@ Parameters:
 | `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
 | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
 | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
+| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** |
 NOTE: **Note:**
 `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added

--- a/doc/api/project_level_variables.md
+++ b/doc/api/project_level_variables.md
@@ -67,13 +67,14 @@ POST /projects/:id/variables
 ```
 | Attribute           | Type    | required | Description           |
-|-----------------|---------|----------|-----------------------|
+|---------------------|---------|----------|-----------------------|
 | `id`                | integer/string | yes      | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user   |
 | `key`               | string  | yes      | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
 | `value`             | string  | yes      | The `value` of a variable |
 | `variable_type`     | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
 | `protected`         | boolean | no       | Whether the variable is protected |
 | `masked`            | boolean | no       | Whether the variable is masked |
+| `environment_scope` | string  | no       | The `environment_scope` of the variable **[PREMIUM]** |
 ```
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
@@ -83,9 +84,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
 {
    "key": "NEW_VARIABLE",
    "value": "new value",
+    "protected": false,
    "variable_type": "env_var",
    "protected": false,
-    "masked": false
+    "masked": false,
+    "environment_scope": "*"
 }
 ```
@@ -98,13 +101,14 @@ PUT /projects/:id/variables/:key
 ```
 | Attribute           | Type    | required | Description             |
-|-----------------|---------|----------|-------------------------|
+|---------------------|---------|----------|-------------------------|
 | `id`                | integer/string | yes      | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user     |
 | `key`               | string  | yes      | The `key` of a variable   |
 | `value`             | string  | yes      | The `value` of a variable |
 | `variable_type`     | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
 | `protected`         | boolean | no       | Whether the variable is protected |
 | `masked`            | boolean | no       | Whether the variable is masked |
+| `environment_scope` | string  | no       | The `environment_scope` of the variable **[PREMIUM]** |
 ```
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"
@@ -116,7 +120,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
    "value": "updated value",
    "variable_type": "env_var",
    "protected": true,
-    "masked": false
+    "masked": false,
+    "environment_scope": "*"
 }
 ```

--- a/doc/api/search.md
+++ b/doc/api/search.md
@@ -19,6 +19,8 @@ GET /search
 Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users.
+If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
 The response depends on the requested scope.
 ### Scope: projects
@@ -281,6 +283,98 @@ Example response:
 ]
 ```
+### Scope: wiki_blobs **[STARTER]**
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. 
+```bash
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=wiki_blobs&search=bye
+```
+Example response:
+```json
+[
+  {
+    "basename": "home",
+    "data": "hello\n\nand bye\n\nend",
+    "filename": "home.md",
+    "id": null,
+    "ref": "master",
+    "startline": 5,
+    "project_id": 6
+  }
+]
+```
+### Scope: commits **[STARTER]**
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
+```bash
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=commits&search=bye
+```
+Example response:
+```json
+[
+  {
+  "id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
+  "short_id": "4109c2d8",
+  "title": "goodbye $.browser",
+  "created_at": "2013-02-18T22:02:54.000Z",
+  "parent_ids": [
+    "59d05353ab575bcc2aa958fe1782e93297de64c9"
+  ],
+  "message": "goodbye $.browser\n",
+  "author_name": "angus croll",
+  "author_email": "anguscroll@gmail.com",
+  "authored_date": "2013-02-18T22:02:54.000Z",
+  "committer_name": "angus croll",
+  "committer_email": "anguscroll@gmail.com",
+  "committed_date": "2013-02-18T22:02:54.000Z",
+  "project_id": 6
+  }
+]
+```
+### Scope: blobs **[STARTER]**
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
+Filters are available for this scope:
+- filename
+- path
+- extension
+to use a filter simply include it in your query like so: `a query filename:some_name*`.
+You may use wildcards (`*`) to use glob matching.
+```bash
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=blobs&search=installation
+```
+Example response:
+```json
+[
+  {
+    "basename": "README",
+    "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
+    "filename": "README.md",
+    "id": null,
+    "ref": "master",
+    "startline": 46,
+    "project_id": 6
+  }
+]
+```
 ### Scope: users
 ```bash
@@ -320,6 +414,8 @@ GET /groups/:id/search
 Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users.
+If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
 The response depends on the requested scope.
 ### Scope: projects
@@ -520,6 +616,98 @@ Example response:
 ]
 ```
+### Scope: wiki_blobs **[STARTER]**
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
+```bash
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=wiki_blobs&search=bye
+```
+Example response:
+```json
+[
+  {
+    "basename": "home",
+    "data": "hello\n\nand bye\n\nend",
+    "filename": "home.md",
+    "id": null,
+    "ref": "master",
+    "startline": 5,
+    "project_id": 6
+  }
+]
+```
+### Scope: commits **[STARTER]**
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
+```bash
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=commits&search=bye
+```
+Example response:
+```json
+[
+  {
+  "id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
+  "short_id": "4109c2d8",
+  "title": "goodbye $.browser",
+  "created_at": "2013-02-18T22:02:54.000Z",
+  "parent_ids": [
+    "59d05353ab575bcc2aa958fe1782e93297de64c9"
+  ],
+  "message": "goodbye $.browser\n",
+  "author_name": "angus croll",
+  "author_email": "anguscroll@gmail.com",
+  "authored_date": "2013-02-18T22:02:54.000Z",
+  "committer_name": "angus croll",
+  "committer_email": "anguscroll@gmail.com",
+  "committed_date": "2013-02-18T22:02:54.000Z",
+  "project_id": 6
+  }
+]
+```
+### Scope: blobs **[STARTER]**
+This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
+Filters are available for this scope:
+- filename
+- path
+- extension
+to use a filter simply include it in your query like so: `a query filename:some_name*`.
+You may use wildcards (`*`) to use glob matching.
+```bash
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=blobs&search=installation
+```
+Example response:
+```json
+[
+  {
+    "basename": "README",
+    "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
+    "filename": "README.md",
+    "id": null,
+    "ref": "master",
+    "startline": 46,
+    "project_id": 6
+  }
+]
+```
 ### Scope: users
 ```bash
@@ -556,7 +744,6 @@ GET /projects/:id/search
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user                |
 | `scope`       | string   | yes        | The scope to search in                |
 | `search`      | string   | yes        | The search query  |
-| `ref`         | string   | no         | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs.  |
 Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users.
@@ -851,7 +1038,7 @@ Blobs searches are performed on both filenames and contents. Search results:
  times in the content.
 ```bash
-curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation&ref=feature
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation
 ```
 Example response:
@@ -864,7 +1051,7 @@ Example response:
    "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
    "filename": "README.md",
    "id": null,
-    "ref": "feature",
+    "ref": "master",
    "startline": 46,
    "project_id": 6
  }