将工作流数据存储为工件

工件允许你在工作流中的作业之间共享数据，并在工作流完成后存储数据。

本文中

关于工作流工件

工件允许你在作业完成后保留数据，并在同一工作流中的另一个作业中共享该数据。工件是在工作流运行期间生成的文件或文件集合。例如，你可以在工作流运行结束后使用工件来保存你的构建和测试输出。在运行中调用的所有操作和工作流都有权写入该运行的工件。

默认情况下，GitHub 存储 90 天的构建日志和工件，此保留期可以自定义。有关更多信息，请参阅“使用限制、计费和管理”。每次有人将新提交推送到拉取请求时，拉取请求的保留期都会重新开始。

以下是你能上传的一些常见工件

  • 日志文件和核心转储
  • 测试结果、失败和屏幕截图
  • 二进制或压缩文件
  • 压力测试性能输出和代码覆盖率结果

存储工件会使用 GitHub 上的存储空间。GitHub Actions 使用是免费的，适用于公共存储库中的标准 GitHub 托管运行程序和自托管运行程序。对于私有存储库，每个 GitHub 帐户都会收到一定数量的免费分钟和存储空间，以用于 GitHub 托管运行程序，具体取决于帐户的计划。超出包含数量的任何使用都受支出限制控制。有关更多信息，请参阅“管理 GitHub Actions 的计费”。

工件在工作流运行期间上传，你可以在 UI 中查看工件的名称和大小。当使用 GitHub UI 下载工件时，作为工件一部分单独上传的所有文件都会压缩到一个文件中。这意味着计费是根据上传的工件大小计算的，而不是 zip 文件的大小。

GitHub 提供两个操作，你可以使用它们来上传和下载构建工件。有关更多信息，请参阅 upload-artifact 和 download-artifact 操作。

在作业之间共享数据

  • 上传文件：为上传的文件命名，并在作业结束前上传数据。
  • 下载文件：你只能下载在同一工作流运行期间上传的工件。下载文件时，你可以按名称引用它。

作业的步骤在运行器计算机上共享相同环境，但会在它们自己的各个进程中运行。若要在作业中的步骤之间传递数据，可以使用输入和输出。有关输入和输出的更多信息，请参阅“GitHub Actions 的元数据语法”。

比较工件和依赖项缓存

工件和缓存类似，因为它们都提供了在 GitHub 上存储文件的功能，但每个功能提供的用例不同，不能互换使用。

  • 当你想重复使用在作业或工作流运行之间不常更改的文件时，可以使用缓存，例如包管理系统中的构建依赖项。
  • 当你想保存作业生成的文件以便在工作流运行结束后查看时，可以使用工件，例如构建的二进制文件或构建日志。

有关依赖项缓存的更多信息，请参阅“缓存依赖项以加速工作流”。

上传构建和测试工件

你可以创建一个持续集成 (CI) 工作流来构建和测试你的代码。有关使用 GitHub Actions 执行 CI 的更多信息，请参阅“关于持续集成”。

构建和测试代码的输出通常会生成你可以用来调试测试失败和可以部署的生产代码的文件。你可以配置一个工作流来构建和测试推送到你的存储库的代码，并报告成功或失败状态。你可以上传构建和测试输出，以便用于部署、调试失败的测试或崩溃，以及查看测试套件覆盖率。

你可以使用 upload-artifact 操作来上传工件。上传工件时，你可以指定单个文件或目录，或多个文件或目录。你还可以排除某些文件或目录，并使用通配符模式。我们建议你为工件提供一个名称，但如果没有提供名称，则 artifact 将用作默认名称。有关语法的更多信息，请参阅 actions/upload-artifact 操作。

示例

例如，你的存储库或 Web 应用程序可能包含 SASS 和 TypeScript 文件，你必须将其转换为 CSS 和 JavaScript。假设你的构建配置在 dist 目录中输出已编译的文件，如果所有测试都成功完成，你将把 dist 目录中的文件部署到你的 Web 应用程序服务器。

|-- hello-world (repository)
|   └── dist
|   └── tests
|   └── src
|       └── sass/app.scss
|       └── app.ts
|   └── output
|       └── test
|

此示例展示了如何为 Node.js 项目创建工作流，该工作流在 src 目录中构建代码并在 tests 目录中运行测试。您可以假设运行 npm test 会生成一个名为 code-coverage.html 的代码覆盖率报告，该报告存储在 output/test/ 目录中。

工作流上传 dist 目录中的生产制品，但会排除任何 markdown 文件。它还会将 code-coverage.html 报告作为另一个制品上传。

YAML
name: Node CI

on: [push]

jobs:
  build_and_test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: npm install, build, and test
        run: |
          npm install
          npm run build --if-present
          npm test
      - name: Archive production artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-without-markdown
          path: |
            dist
            !dist/**/*.md
      - name: Archive code coverage results
        uses: actions/upload-artifact@v4
        with:
          name: code-coverage-report
          path: output/test/code-coverage.html

为构建生成制品证明

注意

制品证明处于公开测试阶段，可能会发生变化。

制品证明使您能够为构建的软件创建不可伪造的出处和完整性保证。反过来，使用您软件的人员可以验证您的软件在何处以及如何构建。

当您使用软件生成制品证明时，您会创建经过加密签名的声明，这些声明建立构建的出处并包括以下信息

  • 指向与制品关联的工作流的链接。
  • 制品的存储库、组织、环境、提交 SHA 和触发事件。
  • 用于建立出处的 OIDC 令牌中的其他信息。有关更多信息，请参阅“关于使用 OpenID Connect 进行安全强化”。

您还可以生成包含关联软件物料清单 (SBOM) 的制品证明。将您的构建与其中使用的开源依赖项列表关联起来，可以提供透明度并使使用者能够遵守数据保护标准。

您可以在构建运行后访问证明，位于构建生成的制品列表下方。

有关更多信息，请参阅“使用制品证明为构建建立出处”。

配置自定义制品保留期

您可以为工作流创建的各个制品定义自定义保留期。在使用工作流创建新制品时，您可以在 upload-artifact 操作中使用 retention-days。此示例演示如何为名为 my-artifact 的制品设置 5 天的自定义保留期

YAML
  - name: 'Upload Artifact'
    uses: actions/upload-artifact@v4
    with:
      name: my-artifact
      path: my_file.txt
      retention-days: 5

retention-days 值不能超过存储库、组织或企业设置的保留期限制。

下载或删除制品

在工作流运行期间，你可以使用 download-artifact 操作下载在同一工作流运行中先前上传的工件。

工作流运行完成后，你可以在 GitHub 上或使用 REST API 下载或删除工件。有关更多信息，请参阅“下载工作流工件”、“删除工作流工件”和“GitHub Actions 工件的 REST API 端点”。

在工作流运行期间下载工件

可以在工作流运行期间使用 actions/download-artifact 操作下载先前上传的工件。

注意：你只能下载在同一工作流运行期间上传到工作流中的工件。

指定工件的名称以下载单个工件。如果你在未指定名称的情况下上传了工件，则默认名称为 artifact。

- name: Download a single artifact
  uses: actions/download-artifact@v4
  with:
    name: my-artifact

你还可以通过不指定名称来下载工作流运行中的所有工件。如果你正在处理大量工件，这会很有用。

- name: Download all workflow run artifacts
  uses: actions/download-artifact@v4

如果你下载所有工作流运行的工件，则会使用其名称为每个工件创建一个目录。

有关语法的更多信息，请参阅 actions/download-artifact 操作。

在工作流中的作业之间传递数据

你可以使用 upload-artifact 和 download-artifact 操作在工作流中的作业之间共享数据。此示例工作流说明了如何在同一工作流中的作业之间传递数据。有关更多信息，请参阅 actions/upload-artifact 和 download-artifact 操作。

依赖于先前作业工件的作业必须等到依赖作业成功完成。此工作流使用 needs 关键字来确保 job_1、job_2 和 job_3 顺序运行。例如，job_2 使用 needs: job_1 语法需要 job_1。

作业 1 执行以下步骤

  • 执行数学计算并将结果保存到名为 math-homework.txt 的文本文件中。
  • 使用 upload-artifact 动作上传 math-homework.txt 文件，工件名称为 homework_pre。

作业 2 使用前一个作业中的结果

  • 下载前一个作业中上传的 homework_pre 工件。默认情况下，download-artifact 动作将工件下载到步骤执行所在的工作空间目录。您可以使用 path 输入参数指定不同的下载目录。
  • 读取 math-homework.txt 文件中的值，执行数学计算，并将结果再次保存到 math-homework.txt，覆盖其内容。
  • 上传 math-homework.txt 文件。由于工件在 v4 中被视为不可变的，因此工件被传递一个不同的输入，homework_final，作为名称。

作业 3 显示前一个作业中上传的结果

  • 从作业 2 下载 homework_final 工件。
  • 将数学方程的结果打印到日志中。

此工作流示例中执行的完整数学运算为 (3 + 7) x 9 = 90。

YAML
name: Share data between jobs

on: [push]

jobs:
  job_1:
    name: Add 3 and 7
    runs-on: ubuntu-latest
    steps:
      - shell: bash
        run: |
          expr 3 + 7 > math-homework.txt
      - name: Upload math result for job 1
        uses: actions/upload-artifact@v4
        with:
          name: homework_pre
          path: math-homework.txt

  job_2:
    name: Multiply by 9
    needs: job_1
    runs-on: windows-latest
    steps:
      - name: Download math result for job 1
        uses: actions/download-artifact@v4
        with:
          name: homework_pre
      - shell: bash
        run: |
          value=`cat math-homework.txt`
          expr $value \* 9 > math-homework.txt
      - name: Upload math result for job 2
        uses: actions/upload-artifact@v4
        with:
          name: homework_final
          path: math-homework.txt

  job_3:
    name: Display results
    needs: job_2
    runs-on: macOS-latest
    steps:
      - name: Download math result for job 2
        uses: actions/download-artifact@v4
        with:
          name: homework_final
      - name: Print the final result
        shell: bash
        run: |
          value=`cat math-homework.txt`
          echo The result is $value

工作流运行将存档它生成的任何工件。有关下载存档工件的更多信息，请参见“下载工作流工件”。

延伸阅读