Skip to content

G
gitlab-ce
Commit 913d440b authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'docs/api-jobs-artifacts' into 'master' 

Fix wrong documentation on jobs API

See merge request gitlab-org/gitlab-ee!9363
parents dcda3295 eeca2c62
Hide whitespace changes
Inline Side-by-side
Showing with 69 additions and 43 deletions
doc/api/jobs.md
View file @ 913d440b
......@@ -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
View file @ 913d440b
......@@ -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
View file @ 913d440b
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7