Job artifacts

原文:https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html

Job artifacts

版本历史

  • 在 GitLab 8.2 和 GitLab Runner 0.7.0 中引入.
  • 从 GitLab 8.4 和 GitLab Runner 1.0 开始,工件存档格式已更改为ZIP ,现在可以浏览其内容,并具有分别下载文件的功能.
  • 在 GitLab 8.17 中,将构建重命名为 job.
  • 工件浏览器仅适用于使用 GitLab Runner 1.0 及更高版本发送到 GitLab 的新工件. 无法浏览已经上传到 GitLab 的旧工件.

作业工件是作业完成后创建的文件和目录的列表. 默认情况下 ,所有 GitLab 安装中均启用此功能.

由 GitLab Runner 创建的作业工件被上传到 GitLab,并可以使用 GitLab UI 或GitLab API作为单个存档下载.

有关概述,请观看视频GitLab CI 管道,工件和环境 . 也请观看面向初学者的 GitLab CI 管道教程 .

Defining artifacts in .gitlab-ci.yml

.gitlab-ci.yml中使用工件定义的一个简单示例如下:

  1. pdf:
  2. script: xelatex mycv.tex
  3. artifacts:
  4. paths:
  5. - mycv.pdf
  6. expire_in: 1 week

名为pdf的作业会调用xelatex命令,以便从乳胶源文件mycv.tex生成 PDF 文件. 然后,我们定义artifacts路径,这些路径又用paths关键字定义. 文件和目录的所有路径都相对于在构建过程中克隆的存储库.

默认情况下,当作业成功时将上传工件,但是可以将其设置为在作业失败时上传,或者如果使用artifacts:when参数,则始终设置为上传. 根据expire_in定义,这些上传的工件将在 GitLab 中保存 1 周. 您可以通过Web 界面防止工件过期. 如果未定义到期时间,则默认为实例范围设置 .

有关工件的更多示例,请遵循.gitlab-ci.yml工件参考 .

artifacts:reports

版本历史

  • 在 GitLab 11.2 中引入 .
  • 需要 GitLab Runner 11.2 及更高版本.

artifacts:reports关键字用于从作业中收集测试报告,代码质量报告和安全性报告. 它还在 GitLab 的 UI 中显示这些报告(合并请求,管道视图和安全性仪表板).

注意:无论作业结果(成功或失败),都将收集测试报告. 您可以使用artifacts:expire_in设置其工件的到期日期.注:如果您还希望能够浏览报告输出文件,请包括artifacts:paths关键字.

artifacts:reports:junit

版本历史

  • 在 GitLab 11.2 中引入 .
  • 需要 GitLab Runner 11.2 及更高版本.

junit报告将JUnit XML 文件收集为工件. 尽管 JUnit 最初是用 Java 开发的,但是还有许多其他端口可以用于其他语言,例如 JavaScript,Python,Ruby 等.

有关更多详细信息和示例,请参见JUnit 测试报告 . 下面是从 Ruby 的 RSpec 测试工具收集 JUnit XML 文件的示例:

  1. rspec:
  2. stage: test
  3. script:
  4. - bundle install
  5. - rspec --format RspecJunitFormatter --out rspec.xml
  6. artifacts:
  7. reports:
  8. junit: rspec.xml

收集的 JUnit 报告将作为工件上传到 GitLab,并将自动显示在合并请求中.

注意:如果您使用的 JUnit 工具导出到多个 XML 文件,则可以在一个作业中指定多个测试报告路径,它们将被自动串联到一个文件中. 使用文件名模式( junit: rspec-*.xml ),文件名数组( junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml] )或其组合( junit: [rspec.xml, test-results/TEST-*.xml] ).

artifacts:reports:dotenv

版本历史

  • 在 GitLab 12.9 中引入 .
  • 需要 GitLab Runner 11.5 及更高版本.

dotenv报告收集一组环境变量作为工件.

收集的变量注册为作业的运行时创建的变量,这对于在作业完成后设置动态环境 URL很有用.

原始 dotenv 规则有两个例外:

  • 可变键只能包含字母,数字和下划线( _ ).
  • .env文件的最大大小为 5 KB.
  • 变量的最大数量为 10.
  • 不支持.env文件中的变量替换.
  • .env文件不能包含空行或注释(以#开头).
  • env文件中的键值不能包含空格或换行符( \n ),包括使用单引号或双引号时.
  • 不支持在解析过程中使用引号转义( key = 'value' -> {key: "value"} ).

artifacts:reports:cobertura

版本历史

The cobertura report collects Cobertura coverage XML files. The collected Cobertura coverage reports will be uploaded to GitLab as an artifact and will be automatically shown in merge requests.

Cobertura 最初是为 Java 开发的,但是有许多第三方端口可用于其他语言,例如 JavaScript,Python,Ruby 等.

artifacts:reports:terraform

版本历史

terraform报告获取 Terraform tfplan.json文件. 需要进行 JQ 处理才能删除凭据 . 收集的 Terraform 计划报告将作为工件上传到 GitLab,并将在合并请求中自动显示. 有关更多信息,请参见将terraform plan信息输出到合并请求中 .

artifacts:reports:codequality

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

codequality报告将CodeQuality 问题收集为工件.

收集的代码质量报告将作为工件上传到 GitLab,并在合并请求中进行汇总.

artifacts:reports:sast

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

sast报告将SAST 漏洞收集为工件.

收集的 SAST 报告将作为工件上传到 GitLab,并将在合并请求和管道视图中进行汇总. 它还用于为安全仪表板提供数据.

artifacts:reports:secret_detection

版本历史

  • 在 GitLab 13.1 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

secret-detection报告将检测到的机密收集为伪像.

收集的 Secret Detection 报告作为工件上传到 GitLab,并在合并请求和管道视图中进行汇总. 它还用于为安全仪表板提供数据.

artifacts:reports:dependency_scanning

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

dependency_scanning报告将” 依赖关系扫描”漏洞收集为工件.

收集的”依赖关系扫描”报告将作为工件上传到 GitLab,并将在合并请求和管道视图中进行汇总. 它还用于为安全仪表板提供数据.

artifacts:reports:container_scanning

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

container_scanning报告收集容器扫描漏洞作为工件.

收集的”容器扫描”报告将作为工件上传到 GitLab,并将在合并请求和管道视图中进行汇总. 它还用于为安全仪表板提供数据.

artifacts:reports:dast

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

dast报告将DAST 漏洞收集为工件.

收集的 DAST 报告将作为工件上传到 GitLab,并将在合并请求和管道视图中进行汇总. 它还用于为安全仪表板提供数据.

artifacts:reports:license_management

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

警告:此工件仍然有效,但不推荐使用 ,而推荐使用 GitLab 12.8 中引入的artifacts:reports:license_scanning .

license_management报告收集许可证作为工件.

The collected License Compliance report will be uploaded to GitLab as an artifact and will be summarized in the merge requests and pipeline view. It’s also used to provide data for security dashboards.

artifacts:reports:license_scanning

版本历史

  • 在 GitLab 12.8 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

license_scanning报告收集许可证作为工件.

许可证合规性报告将作为工件上传到 GitLab,并将自动显示在合并请求,管道视图中,并为安全仪表板提供数据.

artifacts:reports:performance

版本历史

  • 在 GitLab 11.5 中引入.
  • 需要 GitLab Runner 11.5 及更高版本.

performance报告收集浏览器性能测试指标作为工件.

收集的浏览器性能报告将作为工件上传到 GitLab,并将自动显示在合并请求中.

artifacts:reports:load_performance

版本历史

load_performance报告收集工件的负载性能测试指标 .

该报告作为工件被上传到 GitLab,并自动显示在合并请求中.

artifacts:reports:metrics

在 GitLab 11.10 中引入.

metrics报告收集指标作为工件.

收集的指标报告将作为工件上传到 GitLab,并将自动显示在合并请求中.

artifacts:reports:requirements

版本历史

  • 在 GitLab 13.1 中引入 .
  • 需要 GitLab Runner 11.5 及更高版本.

requirements报告收集工件的requirements.json文件.

收集的需求报告将作为工件上传到 GitLab,现有需求将标记为”满意”.

Browsing artifacts

版本历史

  • 从 GitLab 9.2,可以直接在工作工件浏览器中预览 PDF,图像,视频和其他格式,而无需下载它们.
  • GitLab 10.1 中引入的公共项目中的 HTML 文件可以在新选项卡中直接预览,而在启用GitLab Pages时无需下载它们. 文本格式也是如此(当前支持的扩展名: .txt.json.log ).
  • GitLab 12.4 中引入后,启用GitLab 页面访问控制后,便可以预览私有项目中的工件.

作业完成后,如果您访问作业的特定页面,则有三个按钮. 您可以下载工件归档文件或浏览其内容,而” 保留”按钮仅在您为工件设置了有效日期的情况下出现,以防万一您改变主意并希望保留它们.

Job artifacts browser button

存档浏览器显示存档中每个文件的名称和实际文件大小. 如果您的工件包含目录,那么您也可以在其中进行浏览.

您可以在下面看到浏览的样子. 在这种情况下,我们浏览了档案内部,此时有一个目录,几个文件和一个 HTML 文件,启用GitLab 页面 (在新选项卡中打开)后,您可以直接在线查看.

Job artifacts browser

Downloading artifacts

如果您需要下载工件或整个档案,请在 GitLab UI 的不同位置进行操作:

  1. 在管道页面上,您可以在右上角看到每个作业的工件和存档的下载图标:

    Job artifacts in Pipelines page

  2. 在” 作业”页面上,您可以在右上角看到每个作业的工件和存档的下载图标:

    Job artifacts in Builds page

  3. While inside a specific job, you’re presented with a download button along with the one that browses the archive:

    Job artifacts browser button

  4. 最后,在浏览档案时,您可以在右上角看到下载按钮:

    Job artifacts browser

Downloading the latest artifacts

可以通过众所周知的 URL 下载作业的最新工件,以便将其用于脚本目的.

注意:最新工件是由作业在特定引用的最新成功管道中创建的. 如果您为相同的参考运行两种类型的管道,则最新的工件将通过计时来确定. 例如,如果通过合并合并请求创建的分支管道与计划的管道同时运行,则最新的工件将来自最近完成的管道.

可以直接访问其他管道的工件.

用于下载整个工件存档的 URL 的结构如下:

  1. https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>

To download a single file from the artifacts use the following URL:

  1. https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>

例如,要下载名为gitlab项目的master分支(属于gitlab-org命名空间)的coverage的作业的最新工件,URL 为:

  1. https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/download?job=coverage

要从相同的工件下载文件coverage/index.html ,请使用以下 URL:

  1. https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage

还有一个 URL 可浏览最新的作业工件:

  1. https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>

例如:

  1. https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/browse?job=coverage

还有一个指向特定文件的 URL,包括在GitLab 页面中显示的 HTML 文件:

  1. https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>

例如,当一个作业coverage创建神器htmlcov/index.html ,你可以访问它:

  1. https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage

UI 的不同位置也公开了最新版本. 具体来说,请在以下位置查找下载按钮:

  • 主项目页面
  • 分支机构页面
  • 标签页面

如果最新作业未能上传工件,则可以在 UI 中看到该信息.

Latest artifacts button

Erasing artifacts

警告:这是一种破坏性行为,会导致数据丢失. 请谨慎使用.

您可以通过 UI 删除单个作业,如果您是以下情况,则它也将删除作业的工件和跟踪:

删除作业:

  1. 导航到工作页面.
  2. 单击作业跟踪右上方的垃圾桶图标.
  3. 确认删除.

Retrieve artifacts of private projects when using GitLab CI

为了检索不同项目的作业工件,您可能需要使用专用令牌来认证和下载工件.