作业产物

作业可以输出文件和目录的归档。此输出称为作业产物。

你可以通过 GitLab UI 或 API 下载作业产物。

要了解作业产物的概述，观看视频 GitLab CI 流水线、产物和环境。
或作为入门，观看 GitLab CI 流水线教程（初学者）。

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

创建作业产物

要创建作业产物，请在你的 .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，则使用 实例级设置。

要防止产物过期，你可以在作业详情页面选择 保留。当产物未设置过期时间时，该选项不可用。

默认情况下，最新的产物总是被保留。

显式定义产物名称

你可以使用 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"

使用变量扩展

变量扩展支持以下场景：

• artifacts:name
• artifacts:paths
• artifacts:exclude

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

例如，若需创建一个包含当前分支或标签名的归档文件（且仅包含与当前项目同名的目录下的文件），可编写如下 YAML：

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

当分支名包含正斜杠（例如 feature/my-feature）时，应使用 $CI_COMMIT_REF_SLUG 替代 $CI_COMMIT_REF_NAME，以确保制品命名正确。

变量会在globs之前被展开。

获取制品

默认情况下，作业会获取前一阶段定义的所有作业的制品。这些制品会被下载至作业的工作目录中。

你可以通过以下关键字控制下载哪些制品：

• dependencies：指定要从哪些作业下载制品。
• needs：定义作业间的关系并指定要下载哪些制品。

当你使用这些关键字时，默认行为会改变，制品只会从你指定的作业中获取。

防止作业获取制品

若要阻止作业下载任何制品，可将dependencies设置为空数组（[]）：

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

查看项目中所有作业的制品

你可以在项目的 构建 > 制品 页面查看该项目存储的所有制品。此列表会显示所有作业及其关联的制品。展开条目即可访问作业相关的所有制品，包括：

• 通过 artifacts: 关键字创建的制品。
• 报告制品。
• 作业日志和元数据（内部以独立制品形式存储）。

你可从此列表中下载或删除单个制品。

下载作业制品

你可以从以下位置下载作业制品：

• 任意 流水线 列表：在流水线右侧选择 下载制品（ ）。
• 任意 作业 列表：在作业右侧选择 下载制品（ ）。
• 作业详情页：在页面右侧选择 下载。
• 合并请求 概览 页面：在最新流水线右侧选择 制品（ ）。
• 制品 页面：在作业右侧选择 下载（ ）。
• 制品浏览器：在页面顶部选择 下载制品归档包（ ）。

报告制品 仅能从 流水线 列表或 制品 页面下载。

你可以通过作业制品 API下载最新成功流水线的作业制品。除非报告作为常规制品通过 artifacts:paths 添加，否则无法通过作业制品 API 下载制品报告。

从 URL 下载

你可以通过公开可访问的作业制品 API URL 下载特定作业的制品归档包。

例如：

• 下载 GitLab.com 上某项目中 main 分支下名为 build 的作业的最新制品：

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

• 下载 GitLab.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作业令牌

你可以使用CI/CD作业令牌对jobs artifacts API端点进行身份验证，并从不同流水线中获取制品。需指定要检索制品的作业，示例如下：

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列表：作业右侧选择浏览（ ）。
• 作业详情页：页面右侧选择浏览。
• Artifacts页面：作业右侧选择浏览（ ）。

若全局启用了GitLab Pages，即使项目设置中禁用它，也能直接在浏览器预览部分制品文件扩展名；若项目为内部或私有，需开启GitLab Pages访问控制以启用预览。

支持以下扩展名：

通过URL浏览

可通过公开可访问的URL浏览特定作业最新成功流水线的作业制品。例如，在GitLab.com上浏览main分支下名为build的作业最新制品：

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

将<full-project-path>替换为有效项目路径（可在项目URL中找到）。

删除作业日志与制品

你可删除作业的制品与日志。

前提条件：

• 需是该作业的所有者，或拥有项目至少“维护者”角色的用户。

删除作业步骤：

1. 进入作业详情页。
2. 在作业日志右上角选择擦除作业日志和制品（ ）。

也可从Artifacts页面删除单个制品。

批量删除制品

可同时删除多个制品：

1. 左侧边栏选择搜索或前往，找到项目。
2. 选择构建 > 制品。
3. 勾选要删除的制品旁复选框（最多50个）。
4. 选择删除所选。

在合并请求UI中链接作业制品

使用artifacts:expose_as关键字，在合并请求UI中显示作业制品链接。

例如，针对含单个文件的制品：

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

此配置下，GitLab会在对应合并请求的查看暴露的制品区域添加指向file.txt的制品1链接。

保留最近成功作业的制品

默认情况下，每个引用（ref）上的最近一次成功流水线的制品会一直保留。任何 expire_in 配置都不会应用于最近的制品。

当同一引用上的新流水线成功完成时，前一个流水线的制品会根据 expire_in 配置被删除。新流水线的制品会自动保留。

只有当新的流水线针对同一引用运行且满足以下条件时，流水线的制品才会根据 expire_in 配置被删除：

• 成功完成。
• 因手动作业被阻塞而停止运行。

保留最新的制品可能会在包含大量作业或大型制品的项目中使用大量存储空间。如果项目中不需要最新的制品，您可以禁用此行为以节省空间：

1. 在左侧边栏，选择“搜索或前往”并找到您的项目。
2. 选择“设置 > CI/CD”。
3. 展开“制品”。
4. 取消选中“保留最近成功作业的制品”复选框。

禁用此设置后，所有新制品都会根据 expire_in 配置过期。旧流水线中的制品将继续保留，直到同一引用上运行了新流水线。然后该引用下较早流水线的制品也会允许过期。

您可以在 GitLab 自托管实例的实例级 CI/CD 设置中为所有项目禁用此行为。