{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

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

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

获取作业产物

{{< history >}}

{{< /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 >}}

{{< /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 仓库中的分支或标签名称。HEADSHA 引用不支持。
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