存储和共享工作流中的数据

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

本文内容

关于工作流工件

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

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

以下是一些您可以上传的常用工件：

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

存储工件会使用 GitHub 上的存储空间。对于公共存储库中的标准 GitHub 托管运行器以及自托管运行器，GitHub Actions 使用是免费的。对于私有存储库，每个 GitHub 帐户会根据帐户的计划获得一定数量的免费分钟和存储空间，用于与 GitHub 托管运行器一起使用。超出包含数量的任何使用都由支出限制控制。有关更多信息，请参阅“管理 GitHub Actions 的计费”。

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

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

要在作业之间共享数据：

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

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

比较工件和依赖项缓存

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

  • 当您想要重用在作业或工作流运行之间很少更改的文件时，例如来自包管理系统的构建依赖项，请使用缓存。
  • 当您想要保存作业生成的供工作流运行结束后查看的文件时，例如生成的二进制文件或构建日志，请使用工件。

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

上传构建和测试工件

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

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

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

示例

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

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

此示例演示如何为构建src目录中的代码并在tests目录中运行测试的 Node.js 项目创建工作流。您可以假设运行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) 的工件证明。将您的构建与其中使用的开源依赖项列表相关联，可以提高透明度，并使使用者能够遵守数据保护标准。

构建运行后，您可以在构建生成的工件列表下访问证明。

有关更多信息，请参阅“使用工件证明为构建建立来源”。

配置自定义工件保留期

您可以为工作流创建的单个工件定义自定义保留期。使用工作流创建新工件时，您可以将retention-days与upload-artifact操作一起使用。此示例演示如何为名为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

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

进一步阅读