作业产物 API

使用作业产物 API 来下载或删除作业产物。

使用在专业版和旗舰版中可用的 CI/CD 作业令牌 进行身份验证。

获取作业产物#

从项目中获取作业产物的压缩档案。

如果使用 cURL 从 JihuLab.com 下载产物，请使用 --location 参数，因为请求可能会通过 CDN 重定向。

plaintext
GET /projects/:id/jobs/:job_id/artifacts

使用 PRIVATE-TOKEN 头的请求示例：

shell
curl --location --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"

在专业版和旗舰版中，可以通过使用 CI/CD 作业令牌 在 CI/CD 作业中进行身份验证。

使用以下任意一种：

• 使用极狐GitLab 提供的 CI_JOB_TOKEN 预定义变量的 job_token 属性。例如，以下作业下载 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"'

• 使用极狐GitLab 提供的 CI_JOB_TOKEN 预定义变量的 JOB-TOKEN 头。例如，以下作业下载 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"'

可能的响应状态代码：

下载产物档案#

使用引用名称下载最新 成功 流水线中的作业产物的压缩档案。此端点与 获取作业产物 相同，但使用作业的名称而不是 ID。

最新成功的流水线根据创建时间确定。个别作业的开始或结束时间不影响哪个流水线是最新的。

对于 父和子流水线，产物按照从父到子的层次顺序进行搜索。如果父流水线和子流水线都具有同名的作业，则返回父流水线的产物。

前提条件：

• 您必须有一个状态为 success 的已完成流水线。
• 如果流水线包括手动作业，它们必须成功完成，或者设置了 allow_failure: true。

如果使用 cURL 从 JihuLab.com 下载产物，请使用 --location 参数，因为请求可能会通过 CDN 重定向。

plaintext
GET /projects/:id/jobs/artifacts/:ref_name/download?job=name

参数

使用 PRIVATE-TOKEN 头的请求示例：

shell
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test"

在专业版和旗舰版中，可以通过使用 CI/CD 作业令牌 在 CI/CD 作业中进行身份验证。

使用以下任意一种：

• 使用极狐GitLab 提供的 CI_JOB_TOKEN 预定义变量的 job_token 属性。例如，以下作业下载 main 分支的 test 作业产物：

  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"'

• 使用极狐GitLab 提供的 CI_JOB_TOKEN 预定义变量的 JOB-TOKEN 头。例如，以下作业下载 main 分支的 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/main/download?job=test"'

可能的响应状态代码：

通过作业 ID 下载单个产物文件#

使用作业 ID 从作业的压缩产物中下载单个文件。文件从档案中提取并流式传输到客户端。

如果使用 cURL 从 JihuLab.com 下载产物，请使用 --location 参数，因为请求可能会通过 CDN 重定向。

plaintext
GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

参数

请求示例：

shell
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"

在专业版和旗舰版中，可以通过使用 CI/CD 作业令牌 在 CI/CD 作业中进行身份验证。

可能的响应状态代码：

从特定标签或分支下载单个产物文件#

使用引用名称在最新 成功 流水线中从作业的产物中下载单个文件。文件从档案中提取并以 plain/text 内容类型流式传输到客户端。

对于 父和子流水线，产物按照从父到子的层次顺序进行搜索。如果父流水线和子流水线都具有同名的作业，则返回父流水线的产物。

产物文件提供的详细信息比 CSV 导出 中可用的信息更详细。

前提条件：

• 您必须有一个状态为 success 的已完成流水线。
• 如果流水线包括手动作业，它们必须成功完成，或者设置了 allow_failure: true。

如果使用 cURL 从 JihuLab.com 下载产物，请使用 --location 参数，因为请求可能会通过 CDN 重定向。

plaintext
GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name

参数：

请求示例：

shell
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"

在专业版和旗舰版中，可以通过使用 CI/CD 作业令牌 在 CI/CD 作业中进行身份验证。

可能的响应状态代码：

保留产物#

防止在设置过期时删除产物。

plaintext
POST /projects/:id/jobs/:job_id/artifacts/keep

参数

请求示例：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep"

响应示例：

json
1{
2  "commit": {
3    "author_email": "admin@example.com",
4    "author_name": "管理员",
5    "created_at": "2015-12-24T16:51:14.000+01:00",
6    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
7    "message": "测试 CI 集成。",
8    "short_id": "0ff3ae19",
9    "title": "测试 CI 集成。"
10  },
11  "coverage": null,
12  "allow_failure": false,
13  "download_url": null,
14  "id": 42,
15  "name": "rubocop",
16  "ref": "main",
17  "artifacts": [],
18  "runner": null,
19  "stage": "test",
20  "created_at": "2016-01-11T10:13:33.506Z",
21  "started_at": "2016-01-11T10:13:33.506Z",
22  "finished_at": "2016-01-11T10:15:10.506Z",
23  "duration": 97.0,
24  "status": "failed",
25  "failure_reason": "script_failure",
26  "tag": false,
27  "web_url": "https://example.com/foo/bar/-/jobs/42",
28  "user": null
29}

删除作业产物#

删除作业的产物。

前提条件：

• 您必须至少拥有项目的维护者角色。

plaintext
DELETE /projects/:id/jobs/:job_id/artifacts

请求示例：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts"

如果产物成功删除，则返回状态 204 No Content 的响应。

删除项目中的所有作业产物#

删除项目中所有符合删除条件的作业产物。默认情况下，每个引用的最近成功流水线的产物不会被删除。

对此端点的请求将所有可删除作业产物的过期时间设置为当前时间。然后，作为过期作业产物的常规清理的一部分，这些文件从系统中删除。作业日志永远不会被删除。

常规清理异步按计划进行，因此在产物被删除之前可能会有短暂的延迟。

前提条件：

• 您必须至少拥有项目的维护者角色。

plaintext
DELETE /projects/:id/artifacts

请求示例：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/artifacts"

返回状态 202 Accepted 的响应。

故障排除#

下载 artifacts:reports 文件#

在尝试使用作业产物 API 下载报告时，您可能会遇到 404 Not Found 错误。

此问题的发生是因为 报告默认不可下载。

要使报告可下载，请将其文件名或 gl-*-report.json 添加到 artifacts:paths。