{{< details >}}

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

{{< /details >}}

任务可以输出文件和目录的压缩包。这个输出被称为任务产物。

您可以通过使用极狐GitLab UI 或 API 下载任务产物。

有关任务产物存储的管理员信息，请参阅 管理作业产物。

创建任务产物

要创建任务产物，请在 .gitlab-ci.yml 文件中使用 artifacts 关键字：

pdf:
  script: xelatex mycv.tex
  artifacts:
    paths:
      - mycv.pdf

在此示例中，一个名为 pdf 的任务调用 xelatex 命令从 LaTeX 源文件 mycv.tex 构建 PDF 文件。

paths 关键字决定了哪些文件将被添加到任务产物中。所有文件和目录的路径都是相对于创建任务的存储库的。

使用通配符

您可以对路径和目录使用通配符。例如，要创建一个包含所有以 xyz 结尾的目录中的文件的产物：

job:
  script: echo "build xyz project"
  artifacts:
    paths:
      - path/*xyz/*

使用到期时间

expire_in 关键字决定了极狐GitLab 保留 artifacts:paths 中定义的产物多长时间。例如：

pdf:
  script: xelatex mycv.tex
  artifacts:
    paths:
      - mycv.pdf
    expire_in: 1 week

如果未定义 expire_in，则使用 实例级设置。

要防止产物过期，您可以从任务详情页面选择 Keep。当产物没有设置过期时间时，该选项不可用。

默认情况下，最新的产物始终保留。

使用明确定义的产物名称

您可以使用 artifacts:name 配置明确自定义产物名称：

job:
  artifacts:
    name: "job1-artifacts-file"
    paths:
      - binaries/

不包括排除的文件

使用 artifacts:exclude 防止文件被添加到产物压缩包中。

例如，要存储 binaries/ 中的所有文件，但不包括位于 binaries/ 子目录中的 *.o 文件。

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

与 artifacts:paths 不同，exclude 路径不是递归的。要排除目录的所有内容，请明确匹配它们而不是匹配目录本身。

例如，要存储 binaries/ 中的所有文件，但不存储位于 temp/ 子目录中的任何内容：

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/temp/**/*

使用未跟踪的文件

使用 artifacts:untracked 将所有 Git 未跟踪的文件添加为产物（以及在 artifacts:paths 中定义的路径）。未跟踪的文件是那些尚未添加到存储库但存在于存储库检出的文件。

例如，要保存所有 Git 未跟踪的文件和 binaries 中的文件：

artifacts:
  untracked: true
  paths:
    - binaries/

例如，要保存所有未跟踪的文件但 排除 *.txt 文件：

artifacts:
  untracked: true
  exclude:
    - "*.txt"

使用变量扩展

支持以下内容的变量扩展：

极狐GitLab Runner 使用其 内部变量扩展机制，而不是使用 shell。此上下文中仅支持 CI/CD 变量。

例如，要使用当前分支或标签名称创建一个包含仅来自当前项目目录的文件的压缩包：

job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/${CI_PROJECT_NAME}/

当您的分支名称包含正斜杠时（例如，feature/my-feature），使用 $CI_COMMIT_REF_SLUG 而不是 $CI_COMMIT_REF_NAME 来确保正确的产物命名。

获取产物

默认情况下，任务会从前一个阶段定义的任务中获取所有产物。这些产物会下载到任务的工作目录中。

您可以使用以下关键字控制要下载哪些产物：

  • dependencies：指定要从哪些任务下载产物。
  • needs：定义任务之间的关系并指定要下载哪些产物。

当您使用这些关键字时，默认行为会改变，并且产物仅从您指定的任务中获取。

防止任务获取产物

要防止任务下载任何产物，请将 dependencies 设置为空数组 ([])：

job:
  stage: test
  script: make build
  dependencies: []

查看项目中的所有任务产物

{{< history >}}

  • 在极狐GitLab 15.6 中 引入了界面改进。
  • 在极狐GitLab 15.9 中 引入了性能改进。
  • 在极狐GitLab 16.0 中 GA。功能标志 artifacts_management_page 被移除。

{{< /history >}}

您可以从 构建 > 产物 页面查看项目中存储的所有产物。此列表显示所有任务及其关联的产物。展开一个条目以访问与任务关联的所有产物，包括：

  • 使用 artifacts: 关键字创建的产物。
  • 报告产物。
  • 任务日志和元数据，这些都作为单独的产物内部存储。

您可以从此列表中下载或删除单个产物。

下载任务产物

您可以从以下位置下载任务产物：

  • 任何 流水线 列表。在流水线的右侧，选择 下载产物 ({{< icon name=”download” >}})。
  • 任何 作业 列表。在任务的右侧，选择 下载产物 ({{< icon name=”download” >}})。
  • 任务的详情页面。在页面的右侧，选择 下载。
  • 合并请求 概览 页面。在最新流水线的右侧，选择 产物 ({{< icon name=”download” >}})。
  • Artifacts 页面。在任务的右侧，选择 下载 ({{< icon name=”download” >}})。
  • 产物浏览器。在页面顶部，选择 下载产物归档Download artifacts archive ({{< icon name=”download” >}})。

报告产物 只能从 流水线 列表或 产物 页面下载。

您可以使用 任务产物 API 从最新成功的流水线下载任务产物。除非报告作为常规产物添加到 artifacts:paths，否则无法使用任务产物 API 下载 产物报告。

从 URL 下载

您可以通过一个公开访问的 任务产物 API URL 下载特定任务的产物压缩包。

例如：

  • 要从 JihuLab.com 上的项目的 main 分支中下载名为 build 的任务的最新产物：

    https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build

  • 要从 JihuLab.com 上的项目的 main 分支中下载名为 build 的任务的最新文件 review/index.html：

    https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build

    此端点返回的文件始终具有 plain/text 内容类型。

在这两个示例中，将 <project-id> 替换为有效的项目 ID。您可以在 项目概览页面 找到项目 ID。

对于 父子流水线 的产物，按从父到子的层次顺序进行搜索。例如，如果父子流水线都有一个同名的任务，则返回来自父流水线的任务产物。

使用 CI/CD 任务令牌

{{< details >}}

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

{{< /details >}}

您可以使用 CI/CD 任务令牌 进行身份验证，并从不同的流水线中获取产物。您必须指定要从哪个任务检索产物，例如：

build_submodule:
  stage: test
  script:
    - apt update && apt install -y unzip
    - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
    - unzip artifacts.zip

要从同一流水线中的任务获取产物，请使用 needs:artifacts 关键字。

浏览产物压缩包的内容

您可以从 UI 浏览产物的内容，而无需在本地下载产物，来源：

  • 任何 Jobs 列表。在任务的右侧，选择 Browse ({{< icon name=”folder-open” >}})。
  • 任务的详情页面。在页面的右侧，选择 Browse。
  • Artifacts 页面。在任务的右侧，选择 Browse ({{< icon name=”folder-open” >}})。

如果全局启用了 极狐GitLab Pages，即使它在项目设置中被禁用，您仍然可以在浏览器中直接预览某些产物文件扩展名。如果项目是内部的或私有的，您必须启用 极狐GitLab Pages 访问控制 以启用预览。

以下扩展名受支持：

文件扩展名 JihuLab.com 内置 NGINX 的 Linux 软件包
.html {{< icon name=”check-circle” >}} 是 {{< icon name=”check-circle” >}} 是
.json {{< icon name=”check-circle” >}} 是 {{< icon name=”check-circle” >}} 是
.xml {{< icon name=”check-circle” >}} 是 {{< icon name=”check-circle” >}} 是
.txt {{< icon name=”dotted-circle” >}} 否 {{< icon name=”check-circle” >}} 是
.log {{< icon name=”dotted-circle” >}} 否 {{< icon name=”check-circle” >}} 是

从 URL 浏览

您可以通过一个公开访问的 URL 浏览特定任务的最新成功流水线的任务产物。

例如，要浏览 JihuLab.com 上的项目 main 分支中名为 build 的任务的最新产物：

https://gitlab.com/<full-project-path>/-/jobs/artifacts/main/browse?job=build

将 <full-project-path> 替换为有效的项目路径，您可以在项目的 URL 中找到它。

删除任务日志和产物

{{< alert type=”warning” >}}

删除任务日志和产物是一个不可逆的破坏性操作。请谨慎使用。删除某些文件，包括报告产物、任务日志和元数据文件，会影响依赖这些文件作为数据源的极狐GitLab 功能。

{{< /alert >}}

您可以删除任务的产物和日志。

先决条件：

  • 您必须是任务的所有者或项目的至少具有维护者角色的用户。

要删除任务：

  1. 转到任务的详情页面。
  2. 在任务日志的右上角，选择 清除作业和产物 ({{< icon name=”remove” >}})。

您也可以从 产物 页面 删除单个产物。

批量删除产物

{{< history >}}

  • 在极狐GitLab 15.10 中引入，并使用名为 ci_job_artifact_bulk_destroy 的功能标志。默认禁用。
  • 在极狐GitLab 16.1 中 功能标志 ci_job_artifact_bulk_destroy 被移除。

{{< /history >}}

您可以同时删除多个产物：

  1. 在左侧侧边栏中，选择 搜索或转到 并找到您的项目。
  2. 选择 构建 > 产物。
  3. 选择要删除的产物旁边的复选框。您最多可以选择 50 个产物。
  4. 选择 删除所选。

在合并请求 UI 中链接到任务产物

使用 artifacts:expose_as 关键字在 合并请求 UI 中显示到任务产物的链接。

例如，对于一个只有一个文件的产物：

test:
  script: ["echo 'test' > file.txt"]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['file.txt']

使用此配置，极狐GitLab 将 artifact 1 添加为 file.txt 的链接到相关合并请求的 查看暴露的产物 部分。

保留最新成功任务的产物

{{< history >}}

  • 在极狐GitLab 16.7 中，阻止或失败的流水线的产物已不再无限期保留。

{{< /history >}}

默认情况下，产物始终保留在每个 ref 上的最新成功流水线中。任何 expire_in 配置对最新产物不适用。

当同一 ref 上的新流水线成功完成时，先前流水线的产物将根据 expire_in 配置删除。新流水线的产物会自动保留。

仅当为同一 ref 运行新的流水线并且：

  • 成功。
  • 由于被手动任务阻止而停止运行。

时，才会根据 expire_in 配置删除流水线的产物。

在具有大量任务或大产物的项目中，保留最新产物可能会占用大量存储空间。如果项目中不需要最新产物，您可以禁用此行为以节省空间：

  1. 在左侧侧边栏中，选择 搜索或转到 并找到您的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 产物。
  4. 清除 从最近成功的作业中保留产物 复选框。

禁用此设置后，所有新产物将根据 expire_in 配置到期。在为同一 ref 运行新的流水线之前，旧流水线中的产物将继续保留。然后，该 ref 的较早流水线中的产物也将允许过期。

您可以在极狐GitLab 私有化部署的 实例的 CI/CD 设置 中为所有项目禁用此行为。