diff options
Diffstat (limited to 'doc/api/job_artifacts.md')
| -rw-r--r-- | doc/api/job_artifacts.md | 80 |
1 files changed, 51 insertions, 29 deletions
diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index a65de457581..e9d4915da57 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -6,6 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Job Artifacts API **(FREE ALL)** +Use the job artifacts API to download or delete job artifacts. + +Authentication with a [CI/CD job token](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) +available in the Premium and Ultimate tier. + ## Get job artifacts > The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5. @@ -23,7 +28,7 @@ GET /projects/:id/jobs/:job_id/artifacts |---------------------------|----------------|----------|-------------| | `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `job_id` | integer | Yes | ID of a job. | -| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | +| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | Example request using the `PRIVATE-TOKEN` header: @@ -31,29 +36,31 @@ Example request using the `PRIVATE-TOKEN` header: curl --location --output artifacts.zip --location --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/index.md#script) inside -`.gitlab-ci.yml` **(PREMIUM ALL)**, you can use either: +In the Premium and Ultimate tier you can authenticate with this endpoint +in a CI/CD job by using a [CI/CD job token](../ci/jobs/ci_job_token.md). -- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job downloads the artifacts of the job with ID - `42`. The command is wrapped in single quotes because it contains a - colon (`:`): +Use either: + +- The `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` predefined variable. + For example, the following job downloads the artifacts of the job with ID `42`: ```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"' + - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"' ``` -- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. - For example, the following job downloads the artifacts of the job with ID `42`: +- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` predefined variable. + For example, the following job downloads the artifacts of the job with ID + `42`. The command is wrapped in single quotes because it contains a + colon (`:`): ```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"' + - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"' ``` Possible response status codes: @@ -91,7 +98,7 @@ Parameters | `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `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 ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | +| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | Example request using the `PRIVATE-TOKEN` header: @@ -99,30 +106,32 @@ Example request using the `PRIVATE-TOKEN` header: curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test" ``` -To use this in a [`script` definition](../ci/yaml/index.md#script) inside -`.gitlab-ci.yml` **(PREMIUM ALL)**, you can use either: +In the Premium and Ultimate tier you can authenticate with this endpoint +in a CI/CD job by using a [CI/CD job token](../ci/jobs/ci_job_token.md). -- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. +Use either: + +- The `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` predefined variable. For example, the following job downloads the artifacts of the `test` job - of the `main` branch. The command is wrapped in single quotes - because it contains a colon (`:`): + of the `main` branch: ```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/main/download?job=test"' + - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"' ``` -- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. +- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` predefined variable. For example, the following job downloads the artifacts of the `test` job - of the `main` branch: + of the `main` branch. The command is wrapped in single quotes + because it contains a colon (`:`): ```yaml artifact_download: stage: test script: - - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"' + - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test"' ``` Possible response status codes: @@ -152,7 +161,7 @@ Parameters | `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `job_id` | integer | Yes | The unique job identifier. | | `artifact_path` | string | Yes | Path to a file inside the artifacts archive. | -| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | +| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | Example request: @@ -160,6 +169,9 @@ Example request: curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf" ``` +In the Premium and Ultimate tier you can authenticate with this endpoint +in a CI/CD job by using a [CI/CD job token](../ci/jobs/ci_job_token.md). + Possible response status codes: | Status | Description | @@ -196,7 +208,7 @@ Parameters: | `ref_name` | string | Yes | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. | | `artifact_path` | string | Yes | Path to a file inside the artifacts archive. | | `job` | string | Yes | The name of the job. | -| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | +| `job_token` **(PREMIUM ALL)** | string | No | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | Example request: @@ -204,6 +216,9 @@ Example request: curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf" ``` +In the Premium and Ultimate tier you can authenticate with this endpoint +in a CI/CD job by using a [CI/CD job token](../ci/jobs/ci_job_token.md). + Possible response status codes: | Status | Description | @@ -300,9 +315,20 @@ If the artifacts were deleted successfully, a response with status `204 No Conte > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223793) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `bulk_expire_project_artifacts`. Enabled by default on GitLab self-managed. Enabled on GitLab.com. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350609) in GitLab 14.10. -Delete artifacts of a project that can be deleted. +Delete artifacts eligible for deletion in a project. By default, artifacts from +[the most recent successful pipeline of each ref](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). +are not deleted. + +Requests to this endpoint set the expiry of all artifacts that +can be deleted to the current time. The files are then deleted from the system as part +of the regular cleanup of expired job artifacts. Job logs are never deleted. + +The regular cleanup occurs asynchronously on a schedule, so there might be a short delay +before artifacts are deleted. -By default, [artifacts from the most recent successful pipeline of each ref are kept](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). +Prerequisite: + +- You must have at least the Maintainer role for the project. ```plaintext DELETE /projects/:id/artifacts @@ -318,8 +344,4 @@ Example request: curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/artifacts" ``` -NOTE: -At least Maintainer role is required to delete artifacts. - -Schedules a worker to update to the current time the expiry of all artifacts that can be deleted. A response with status `202 Accepted` is returned. |