diff options
Diffstat (limited to 'doc/api/jobs.md')
| -rw-r--r-- | doc/api/jobs.md | 103 |
1 files changed, 83 insertions, 20 deletions
diff --git a/doc/api/jobs.md b/doc/api/jobs.md index d51451b9c83..72973b69117 100644 --- 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. | +| 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 | -| 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 @@ -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 -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 @@ -388,24 +420,51 @@ 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. | +| 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 | -| 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 @@ -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 |