Add docs for "Allow CI_JOB_TOKEN in artifact download API"

doc/api/jobs.md

@@ -294,9 +294,12 @@ Example of response
 
 ## Get job artifacts
 
-> [Introduced][ce-2893] in GitLab 8.5
+> **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 Enterprise Edition Premium][ee] 9.5.
 
-Get job artifacts of a project
+Get job artifacts of a project.
 
 ```
 GET /projects/:id/jobs/:job_id/artifacts
@@ -306,10 +309,27 @@ GET /projects/:id/jobs/:job_id/artifacts
 |------------|---------|----------|---------------------|
 | `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `job_id` | integer | yes      | The ID of a job   |
+| `job_token` | string  | no       | To be used with [triggers] for multi-project pipelines. Is should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
-```
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts"
-```
+Example requests:
+
+- Using the `PRIVATE-TOKEN` header:
+
+    ```
+    curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+    ```
+
+- Using the `JOB-TOKEN` header (only inside `.gitlab-ci.yml`):
+
+    ```
+    curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+    ```
+
+- Using the `job_token` parameter (only inside `.gitlab-ci.yml`):
+
+    ```
+    curl --header -form "job-token=$CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+    ```
 
 Response:
 
@@ -322,7 +342,10 @@ Response:
 
 ## Download the artifacts file
 
-> [Introduced][ce-5347] in GitLab 8.10.
+> **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 Enterprise Edition Premium][ee] 9.5.
 
 Download the artifacts file from the given reference name and job provided the
 job finished successfully.
@@ -338,12 +361,27 @@ Parameters
 | `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user       |
 | `ref_name`  | string  | yes      | The ref from a repository |
 | `job`       | string  | yes      | The name of the job       |
+| `job_token` | string  | no       | To be used with [triggers] for multi-project pipelines. Is should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
-Example request:
+Example requests:
 
-```
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
-```
+- Using the `PRIVATE-TOKEN` header:
+
+    ```
+    curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+    ```
+
+- Using the `JOB-TOKEN` header (only inside `.gitlab-ci.yml`):
+
+    ```
+    curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+    ```
+
+- Using the `job_token` parameter (only inside `.gitlab-ci.yml`):
+
+    ```
+    curl --header -form "job-token=$CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+    ```
 
 Example response:
 
@@ -615,3 +653,7 @@ Example of response
   "user": null
 }
 ```
+
+[ee]: https://about.gitlab.com/gitlab-ee/
+[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

doc/ci/triggers/README.md

@@ -18,11 +18,14 @@ A unique trigger token can be obtained when [adding a new trigger](#adding-a-new
 
 ### CI job token
 
-> **Note**:
-[Introduced][ee-2017] in [GitLab Enterprise Edition Premium][ee] 9.3
+You can use the `CI_JOB_TOKEN` [variable][predef] (used to authenticate
+with the [GitLab Container Registry][registry]) in the following cases.
+
+#### When used with multi-project pipelines
 
-You can trigger a new pipeline using the `CI_JOB_TOKEN` [variable][predef]
-which is used to authenticate with the [GitLab Container Registry][registry].
+> **Note**:
+The use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced][ee-2017]
+in [GitLab Enterprise Edition Premium][ee] 9.3.
 
 This way of triggering can only be used when invoked inside `.gitlab-ci.yml`,
 and it creates a dependent pipeline relation visible on the
@@ -40,7 +43,34 @@ build_docs:
 Pipelines triggered that way also expose a special variable:
 `CI_PIPELINE_SOURCE=pipeline`.
 
-For more information, read about [triggering a pipeline](#triggering-a-pipeline).
+Read more about the [pipelines trigger API][trigapi].
+
+#### When a pipeline depends on the artifacts of another pipeline
+
+> **Note**:
+The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
+in [GitLab Enterprise Edition Premium][ee] 9.5.
+
+With the introduction of dependencies between different projects, one of
+them may need to access artifacts created by a previous one. This process
+must be granted for authorized accesses, and it can be done using the
+`CI_JOB_TOKEN` variable that identifies a specific job. For example:
+
+```yaml
+build_submodule:
+  stage: test
+  script:
+  - curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+  - unzip artifacts.zip
+  only:
+  - tags
+```
+
+This allows you to use that for multi-project pipelines and download artifacts
+from any project to which you have access as this follows the same principles
+with the [permission model][permissions].
+
+Read more about the [jobs API].
 
 ## Adding a new trigger
 
@@ -244,8 +274,12 @@ removed with one of the future versions of GitLab. You are advised to
 [take ownership](#taking-ownership) of any legacy triggers.
 
 [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017
+[ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346
 [ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229
 [ee]: https://about.gitlab.com/gitlab-ee/
 [variables]: ../variables/README.md
 [predef]: ../variables/README.md#predefined-variables-environment-variables
 [registry]: ../../user/project/container_registry.md
+[permissions]: ../../user/permissions.md#jobs-permissions
+[trigapi]: ../../api/pipeline_triggers.md
+[jobs api]: ../../api/jobs.md

doc/ci/variables/README.md

@@ -50,7 +50,7 @@ future GitLab releases.**
 | **CI_JOB_MANUAL**               | 8.12   | all    | The flag to indicate that job was manually started |
 | **CI_JOB_NAME**                 | 9.0    | 0.5    | The name of the job as defined in `.gitlab-ci.yml` |
 | **CI_JOB_STAGE**                | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml` |
-| **CI_JOB_TOKEN**                | 9.0    | 1.2    | Token used for authenticating with the GitLab Container Registry |
+| **CI_JOB_TOKEN**                | 9.0    | 1.2    | Token used for authenticating with the GitLab Container Registry. Also used to authenticate with multi-project pipelines when [triggers][trigger-job-token] are involved. |
 | **CI_REPOSITORY_URL**           | 9.0    | all    | The URL to clone the Git repository |
 | **CI_RUNNER_DESCRIPTION**       | 8.10   | 0.5    | The description of the runner as saved in GitLab |
 | **CI_RUNNER_ID**                | 8.10   | 0.5    | The unique id of runner being used |
@@ -461,3 +461,4 @@ export CI_REGISTRY_PASSWORD="longalfanumstring"
 [triggered]: ../triggers/README.md
 [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger
 [subgroups]: ../../user/group/subgroups/index.md
+[trigger-job-token]: ../triggers/README.md#ci-job-token