Help us learn about your current experience with the documentation. Take the survey.

作业产物 API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 下载、保留和删除作业产物。

使用 CI/CD 作业令牌进行身份验证

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

在 CI/CD 作业中下载作业产物时，您可以使用 CI/CD 作业令牌 对多项目流水线进行身份验证。此方法仅应用于 .gitlab-ci.yml 文件中定义的 CI/CD 作业。

使用 $CI_JOB_TOKEN 时，关联的作业必须处于运行状态。

使用以下任一方式：

  • 使用 job_token 参数配合 CI_JOB_TOKEN 预定义变量。
  • 使用 JOB-TOKEN 请求头配合 CI_JOB_TOKEN 预定义变量。

更多信息，请参阅 REST API 身份验证。

通过作业 ID 下载作业产物

使用作业 ID 下载作业的产物存档。

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

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

支持的属性：

属性 类型 必填 说明
id integer/string 是 项目 ID 或 URL 编码的项目路径。
job_id integer 是 作业 ID。
job_token string 否 多项目流水线的 CI/CD 作业令牌。仅限 Premium 和 Ultimate 版本。

成功时返回 200 状态码并提供产物文件。

请求示例：

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

使用 CI/CD 作业令牌的请求示例：

# 使用 job_token 参数
artifact_download:
  stage: test
  script:
    - 'curl --location --output artifacts.zip \
         --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"'

通过引用名称下载作业产物

使用引用名称下载最新成功流水线中作业的产物存档。

最新成功流水线基于创建时间确定。单个作业的开始或结束时间不影响流水线的最新性判定。

对于父流水线和子流水线，产物按从父到子的层级顺序搜索。如果父流水线和子流水线存在同名作业，则返回父流水线的产物。

前置条件：

  • 必须存在状态为 success 的已完成流水线。
  • 如果流水线包含手动作业，则必须：
    • 成功完成。
    • 设置 allow_failure: true。

如果使用 cURL 从 GitLab.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 引用。对于合并请求流水线，请使用 ref/merge-requests/:iid/head 替代分支名称。
job_token string 否 多项目流水线的 CI/CD 作业令牌。仅限 Premium 和 Ultimate 版本。

成功时返回 200 状态码并提供产物文件。

请求示例：

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

使用 CI/CD 作业令牌的请求示例：

# 使用 job_token 参数
artifact_download:
  stage: test
  script:
    - 'curl --location --output artifacts.zip \
         --url "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"'

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

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

如果使用 cURL 从 GitLab.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 否 多项目流水线的 CI/CD 作业令牌。仅限 Premium 和 Ultimate 版本。

成功时返回 200 状态码并发送单个产物文件。

请求示例：

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

通过引用名称下载单个产物文件

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

对于父流水线和子流水线，产物按从父到子的层级顺序搜索。如果父流水线和子流水线存在同名作业，则返回父流水线的产物。

产物文件提供的详细信息比 CSV 导出 更丰富。

前置条件：

  • 必须存在状态为 success 的已完成流水线。
  • 如果流水线包含手动作业，则必须：
    • 成功完成。
    • 设置 allow_failure: true。

如果使用 cURL 从 GitLab.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 引用。对于合并请求流水线，请使用 ref/merge-requests/:iid/head 替代分支名称。
job_token string 否 多项目流水线的 CI/CD 作业令牌。仅限 Premium 和 Ultimate 版本。

成功时返回 200 状态码并发送单个产物文件。

请求示例：

curl --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf"

保留作业产物

防止作业产物在到期时被自动删除。

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

支持的属性：

属性 类型 必填 说明
id integer/string 是 项目 ID 或 URL 编码的项目路径。
job_id integer 是 作业 ID。

成功时返回 200 状态码和作业详情。

请求示例：

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

响应示例：

{
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "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
}

删除作业产物

删除与特定作业关联的所有产物。产物删除后无法恢复。

前置条件：

  • 必须至少拥有项目的 Maintainer 角色。
DELETE /projects/:id/jobs/:job_id/artifacts

支持的属性：

属性 类型 必填 说明
id integer/string 是 项目 ID 或 URL 编码的项目路径。
job_id integer 是 作业 ID。

成功时返回 204 No Content 状态码。

请求示例：

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

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

删除项目中所有可删除的作业产物。产物删除后无法恢复。

默认情况下，每个引用的最新成功流水线 的产物不会被删除。

对此端点的请求会将所有可删除作业产物的过期时间设置为当前时间。随后文件将在定期清理过期作业产物时从系统中删除。作业日志永远不会被删除。

定期清理是按计划异步执行的，因此产物删除前可能会有短暂延迟。

前置条件：

  • 必须至少拥有项目的 Maintainer 角色。
DELETE /projects/:id/artifacts

支持的属性：

属性 类型 必填 说明
id integer/string 是 项目 ID 或 URL 编码的项目路径。

成功时返回 202 Accepted 状态码。

请求示例：

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

故障排除

在合并请求流水线中使用分支名称

使用分支名称作为 ref_name 下载作业产物时，可能会遇到 404 Not Found 错误。

此问题发生是因为合并请求流水线使用的引用格式与分支流水线不同。合并请求流水线运行在 refs/merge-requests/:iid/head 上，而非直接在源分支上运行。

要下载合并请求流水线的作业产物，请使用 ref/merge-requests/:iid/head 作为 ref_name（:iid 为合并请求 ID），而非分支名称。

例如，对于合并请求 !123：

curl --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/ref/merge-requests/123/head/raw/file.txt?job=test"

下载 artifacts:reports 文件

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

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

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