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

先决条件

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

上传构建和测试构件

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

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

此示例演示了如何创建 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

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

配置自定义构件保留期

您可以为工作流程创建的单个构件自定义保留期。使用工作流创建新工件时，可以同时使用 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

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

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

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

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

注意

如果要从其他工作流或工作流运行下载工件，你需要提供令牌和运行标识符。请参阅针对 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 操作上的 download-artifact 操作。

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

作业1执行以下步骤：

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

作业 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

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

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

验证工件

每次使用 upload-artifact 操作时，都会返回名为 digest 的输出。这是工作流运行期间上传的工件的 SHA256 摘要。

当随后使用 download-artifact 操作下载该工件时，它会自动计算下载工件的摘要，并验证其是否与 upload-artifact 步骤的输出相匹配。

如果摘要不匹配，则运行将在 UI 和作业日志中显示警告。

若要查看 SHA256 摘要，打开 upload-artifact 作业的日志，或检查工作流运行 UI 中显示的工件输出。

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

本文内容