使用工作流工件存储和共享数据

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

本文内容

先决条件

在完成本教程之前，需要理解工作流工件。 请参阅“工作流项目”。

上传构建和测试构件

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

可以使用 upload-artifact 操作上传工件。 上传构件时，您可以指定单个文件或目录，或多个文件或目录。 您还可以排除某些文件或目录，以及使用通配符模式。 建议为工件命名，如果没有命名，则会使用 artifact 作为默认名称。 有关语法的详细信息，请参阅 GitHub Enterprise Server 上的 actions/upload-artifact 操作。

示例

例如，您的仓库或 Web 应用程序可能包含必须转换为 CSS 和 JavaScript 的 SASS 和 TypeScript 文件。 假设生成配置输出 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@v3
        with:
          name: dist-without-markdown
          path: |
            dist
            !dist/**/*.md
      - name: Archive code coverage results
        uses: actions/upload-artifact@v3
        with:
          name: code-coverage-report
          path: output/test/code-coverage.html

配置自定义构件保留期

您可以为工作流程创建的单个构件自定义保留期。 使用工作流创建新工件时，可以同时使用 retention-days 和 upload-artifact 操作。 此示例演示如何为名为 my-artifact 的工件设置 5 天的自定义保留期：

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

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

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

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

注意

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

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

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

您还可以不指定名称而下载工作流程运行中的所有构件。 如果您在处理大量构件，此功能非常有用。

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

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

有关语法的详细信息，请参阅 GitHub Enterprise Server 上的 actions/download-artifact 操作。

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

可以使用 upload-artifact 和 download-artifact 操作在工作流中的作业间共享数据。 此示例工作流程说明如何在相同工作流程中的任务之间传递数据。 有关详细信息，请参阅 actions/upload-artifact 和 GitHub Enterprise Server 上的 download-artifact 操作。

依赖于以前作业构件的作业必须等待依赖项成功完成。 此工作流使用 needs 密钥来确保 job_1、job_2 和 job_3 按顺序运行。 例如，job_2 需要 job_1，方法是使用 needs: job_1 语法。

作业1执行以下步骤：

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

作业 2 使用上一个作业的结果：

  • 下载在上一个作业中上传的 homework 构件。 默认情况下，download-artifact 操作会将工件下载到该步骤执行的工作区目录中。 可以使用 path 输入参数指定不同的下载目录。
  • 读取 math-homework.txt 文件中的值，执行数学计算，并再次将结果保存到 math-homework.txt，覆盖其内容。
  • 上传 math-homework.txt 文件。 此上传将覆盖以前上传的构件，因为其共享相同的名称。

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

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

在此工作流示例中执行的完整数学运算是 (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@v3
        with:
          name: homework
          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@v3
        with:
          name: homework
      - 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@v3
        with:
          name: homework
          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@v3
        with:
          name: homework
      - name: Print the final result
        shell: bash
        run: |
          value=`cat math-homework.txt`
          echo The result is $value

工作流程运行运行将会存档它生成的任何构件。 有关下载已存档项目的详细信息，请参阅“下载工作流程构件”。