{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 私有化部署
{{< /details >}}
使用作业产物 API 来下载或删除作业产物。
使用在专业版和旗舰版中可用的 CI/CD 作业令牌 进行身份验证。
获取作业产物
{{< history >}}
- 在极狐GitLab 专业版 9.5 中,引入了在产物下载 API 中使用
CI_JOB_TOKEN
。
{{< /history >}}
从项目中获取作业产物的压缩档案。
如果使用 cURL 从 JihuLab.com 下载产物,请使用 --location
参数,因为请求可能会通过 CDN 重定向。
GET /projects/:id/jobs/:job_id/artifacts
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
job_id |
integer | 是 | 作业的 ID。 |
job_token |
string | 否 | 用于多项目流水线的 触发器。它应该只在 .gitlab-ci.yml 文件中定义的 CI/CD 作业中调用。值总是 $CI_JOB_TOKEN 。使用此令牌时,关联的作业必须正在运行。仅限专业版和旗舰版。 |
使用 PRIVATE-TOKEN
头的请求示例:
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
的作业产物: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
的作业产物。命令被单引号包裹,因为它包含一个冒号 (:
):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"'
可能的响应状态代码:
状态 | 描述 |
---|---|
200 | 提供产物文件。 |
404 | 找不到构建,没有产物,或者所有产物都是报告。 |
下载产物档案
{{< history >}}
- 在极狐GitLab 专业版 9.5 中,引入了在产物下载 API 中使用
CI_JOB_TOKEN
。
{{< /history >}}
使用引用名称下载最新 成功 流水线中的作业产物的压缩档案。此端点与 获取作业产物 相同,但使用作业的名称而不是 ID。
最新成功的流水线根据创建时间确定。个别作业的开始或结束时间不影响哪个流水线是最新的。
对于 父和子流水线,产物按照从父到子的层次顺序进行搜索。如果父流水线和子流水线都具有同名的作业,则返回父流水线的产物。
前提条件:
- 您必须有一个状态为
success
的已完成流水线。 - 如果流水线包括手动作业,它们必须成功完成,或者设置了
allow_failure: true
。
如果使用 cURL 从 JihuLab.com 下载产物,请使用 --location
参数,因为请求可能会通过 CDN 重定向。
GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
参数
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
job |
string | 是 | 作业的名称。 |
ref_name |
string | 是 | 仓库中的分支或标签名称。HEAD 或 SHA 引用不支持。 |
job_token |
string | 否 | 用于多项目流水线的 触发器。它应该只在 .gitlab-ci.yml 文件中定义的 CI/CD 作业中调用。值总是 $CI_JOB_TOKEN 。使用此令牌时,关联的作业必须正在运行。仅限专业版和旗舰版。 |
使用 PRIVATE-TOKEN
头的请求示例:
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
作业产物: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
作业产物。命令被单引号包裹,因为它包含一个冒号 (:
):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"'
可能的响应状态代码:
状态 | 描述 |
---|---|
200 | 提供产物文件。 |
404 | 找不到构建,没有产物,或者所有产物都是报告。 |
通过作业 ID 下载单个产物文件
使用作业 ID 从作业的压缩产物中下载单个文件。文件从档案中提取并流式传输到客户端。
如果使用 cURL 从 JihuLab.com 下载产物,请使用 --location
参数,因为请求可能会通过 CDN 重定向。
GET /projects/:id/jobs/:job_id/artifacts/*artifact_path
参数
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
artifact_path |
string | 是 | 产物档案内文件的路径。 |
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
job_id |
integer | 是 | 唯一作业标识符。 |
job_token |
string | 否 | 用于多项目流水线的 触发器。它应该只在 .gitlab-ci.yml 文件中定义的 CI/CD 作业中调用。值总是 $CI_JOB_TOKEN 。使用此令牌时,关联的作业必须正在运行。仅限专业版和旗舰版。 |
请求示例:
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 作业中进行身份验证。
可能的响应状态代码:
状态 | 描述 |
---|---|
200 | 发送单个产物文件。 |
400 | 提供的路径无效。 |
404 | 找不到构建,没有产物,或者所有产物都是报告。 |
从特定标签或分支下载单个产物文件
使用引用名称在最新 成功 流水线中从作业的产物中下载单个文件。文件从档案中提取并以 plain/text
内容类型流式传输到客户端。
对于 父和子流水线,产物按照从父到子的层次顺序进行搜索。如果父流水线和子流水线都具有同名的作业,则返回父流水线的产物。
产物文件提供的详细信息比 CSV 导出 中可用的信息更详细。
前提条件:
- 您必须有一个状态为
success
的已完成流水线。 - 如果流水线包括手动作业,它们必须成功完成,或者设置了
allow_failure: true
。
如果使用 cURL 从 JihuLab.com 下载产物,请使用 --location
参数,因为请求可能会通过 CDN 重定向。
GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
artifact_path |
string | 是 | 产物档案内文件的路径。 |
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
job |
string | 是 | 作业的名称。 |
ref_name |
string | 是 | 仓库中的分支或标签名称。HEAD 或 SHA 引用不支持。 |
job_token |
string | 否 | 用于多项目流水线的 触发器。它应该只在 .gitlab-ci.yml 文件中定义的 CI/CD 作业中调用。值总是 $CI_JOB_TOKEN 。使用此令牌时,关联的作业必须正在运行。仅限专业版和旗舰版。 |
请求示例:
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 作业中进行身份验证。
可能的响应状态代码:
状态 | 描述 |
---|---|
200 | 发送单个产物文件。 |
400 | 提供的路径无效。 |
404 | 找不到构建,没有产物,或者所有产物都是报告。 |
保留产物
防止在设置过期时删除产物。
POST /projects/:id/jobs/:job_id/artifacts/keep
参数
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
job_id |
integer | 是 | 作业的 ID。 |
请求示例:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep"
响应示例:
{
"commit": {
"author_email": "admin@example.com",
"author_name": "管理员",
"created_at": "2015-12-24T16:51:14.000+01:00",
"id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
"message": "测试 CI 集成。",
"short_id": "0ff3ae19",
"title": "测试 CI 集成。"
},
"coverage": null,
"allow_failure": false,
"download_url": null,
"id": 42,
"name": "rubocop",
"ref": "main",
"artifacts": [],
"runner": null,
"stage": "test",
"created_at": "2016-01-11T10:13:33.506Z",
"started_at": "2016-01-11T10:13:33.506Z",
"finished_at": "2016-01-11T10:15:10.506Z",
"duration": 97.0,
"status": "failed",
"failure_reason": "script_failure",
"tag": false,
"web_url": "https://example.com/foo/bar/-/jobs/42",
"user": null
}
删除作业产物
删除作业的产物。
前提条件:
- 您必须至少拥有项目的维护者角色。
DELETE /projects/:id/jobs/:job_id/artifacts
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
job_id |
integer | 是 | 作业的 ID。 |
请求示例:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts"
{{< alert type=”note” >}}
删除产物至少需要维护者角色。
{{< /alert >}}
如果产物成功删除,则返回状态 204 No Content
的响应。
删除项目中的所有作业产物
删除项目中所有符合删除条件的作业产物。默认情况下,每个引用的最近成功流水线的产物不会被删除。
对此端点的请求将所有可删除作业产物的过期时间设置为当前时间。然后,作为过期作业产物的常规清理的一部分,这些文件从系统中删除。作业日志永远不会被删除。
常规清理异步按计划进行,因此在产物被删除之前可能会有短暂的延迟。
前提条件:
- 您必须至少拥有项目的维护者角色。
DELETE /projects/:id/artifacts
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或 URL 编码路径。 |
请求示例:
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
。