Fix wrong documentation on artifacts API

doc/api/jobs.md

@@ -344,7 +344,7 @@ Example of response
 > - 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
@@ -354,34 +354,45 @@ 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. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `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:
 
-- Using the `PRIVATE-TOKEN` header:
+```sh
+curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"
+```
 
-    ```sh
-    curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts"
-    ```
+To use this in a [`script` definition](../ci/yaml/README.md#script) inside
+`.gitlab-ci.yml`, you can use either:
 
-- Using the `JOB-TOKEN` header (only inside `.gitlab-ci.yml`):
+- 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 (`:`):
 
-    ```sh
-    curl --location --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts"
-    ```
+  ```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"'
+  ```
 
-- Using the `job_token` parameter (only inside `.gitlab-ci.yml`):
+- 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`:
 
-    ```sh
-    curl --location --form "job-token=$CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts"
-    ```
+  ```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       |
-| 404       | Build not found or no artifacts |
+| 200       | Serves the artifacts file.      |
+| 404       | Build not found or no artifacts.|
 
 [ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893
 
@@ -393,8 +404,10 @@ Possible response status codes:
 > - 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
-job finished successfully.
+Download the artifacts zipped archive from the given reference name and job,
+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
@@ -407,34 +420,46 @@ 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      | Branch or tag name in repository. HEAD or SHA references are not supported.                                                                     |
 | `job`       | string         | yes      | The name of the job.                                                                                                                            |
-| `job_token` | 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`. |
+| `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:
 
-- 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"
+```
 
-    ```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`, you can use either:
 
-- Using the `JOB-TOKEN` header (only inside `.gitlab-ci.yml`):
+- 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 (`:`):
 
-    ```sh
-    curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
-    ```
+  ```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"'
+  ```
 
-- Using the `job_token` parameter (only inside `.gitlab-ci.yml`):
+- 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:
 
-    ```sh
-    curl --header --form "job-token=$CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
-    ```
+  ```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       |
-| 404       | Build not found or no artifacts |
+| 200       | Serves the artifacts file.      |
+| 404       | Build not found or no artifacts.|
 
 [ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347
 
@@ -443,7 +468,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,4 +808,4 @@ Example of response
 
 [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
+[triggers]: ../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium

doc/ci/triggers/README.md

@@ -48,9 +48,8 @@ Read more about the [pipelines trigger API][trigapi].
 
 #### When a pipeline depends on the artifacts of another pipeline **[PREMIUM]**
 
-> **Note**:
-The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
-in [GitLab Premium][ee] 9.5.
+> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
+  in [GitLab 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
@@ -59,9 +58,11 @@ must be granted for authorized accesses, and it can be done using the
 
 ```yaml
 build_submodule:
+  image: debian
   stage: test
   script:
-  - curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
+  - apt update && apt install -y unzip
+  - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"
   - unzip artifacts.zip
   only:
   - tags
@@ -71,7 +72,7 @@ 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].
+Read more about the [jobs API](../../api/jobs.md#download-the-artifacts-archive).
 
 ## Adding a new trigger
 
@@ -285,4 +286,3 @@ removed with one of the future versions of GitLab. You are advised to
 [registry]: ../../user/project/container_registry.md
 [permissions]: ../../user/permissions.md#job-permissions
 [trigapi]: ../../api/pipeline_triggers.md
-[jobs api]: ../../api/jobs.md

doc/ci/yaml/README.md

@@ -204,6 +204,7 @@ job:
     - bundle exec rspec
 ```
 
+CAUTION: **Be careful with commands containing special characters:**
 Sometimes, `script` commands will need to be wrapped in single or double quotes.
 For example, commands that contain a colon (`:`) need to be wrapped in quotes so
 that the YAML parser knows to interpret the whole thing as a string rather than