重新使用工作流

概述

您可以使工作流程可重复使用，而不是从一个工作流程复制并粘贴到另一个工作流程。然后，您和有权访问可重用工作流程的任何人都可以从另一个工作流程调用可重用工作流程。

重用工作流程可避免重复。这使得工作流程更易于维护，并允许您通过构建他人的工作来更快地创建新工作流程，就像您对操作所做的那样。工作流重用还通过帮助你使用设计良好、已经过测试且已证明有效的工作流来促进最佳做法。您的组织可以构建可集中维护的可重用工作流程库。

下图显示了使用可重用工作流的正在进行的工作流运行。

在该图左侧的三个生成作业均成功完成后，将运行一个名为“部署”的依赖作业。
“部署”作业调用包含三个作业的可重用工作流：“暂存”、“审阅”和“生产”。
“生产”部署作业仅在“暂存”作业成功完成后运行。
当作业以环境为目标时，工作流运行会显示一个进度条，其中显示作业中的步骤数。在下图中，“生产”作业包含 8 个步骤，目前正在处理步骤 6。
使用可重用工作流程运行部署作业，可以为每个构建运行这些作业，而无需在工作流程中重复代码。

调用可重用工作流的工作流示意图。

使用其他工作流程的工作流程称为“调用方”工作流程。可重用工作流程是“被调用”工作流程。一个调用方工作流程可以使用多个被调用的工作流程。每个被调用的工作流程都在一行中引用。结果是，调用方工作流程文件可能只包含几行 YAML，但在运行时可能会执行大量任务。当您重用工作流程时，将使用整个被调用的工作流程，就像它是调用方工作流程的一部分一样。

如果重用其他存储库中的工作流程，则被调用工作流程中的任何操作都将像调用方工作流程的一部分一样运行。例如，如果被调用的工作流使用 actions/checkout，则该操作将签出托管调用方工作流（而不是被调用的工作流）的存储库的内容。

当可重用工作流由调用方工作流触发时，github 上下文始终与调用方工作流关联。调用的工作流会自动授予对 github.token 和 secrets.GITHUB_TOKEN 访问权限。有关 github 上下文的详细信息，请参阅“上下文”。

您可以将 GitHub Actions 工作流程中引用的重用工作流程视为包含工作流程的仓库依赖图中的依赖项。有关详细信息，请参阅“关于依赖项关系图”。

可重用工作流程和入门工作流程

组织中所有有权创建工作流的人员都可利用入门工作流更快、更轻松地创建工作流。当用户创建新工作流程时，他们可以选择入门工作流程，并且将为他们完成编写工作流程的部分或全部工作。在入门工作流程中，您还可以引用可重用的工作流程，以便人们能够轻松地从重用集中管理的工作流程代码中受益。如果在引用可重用工作流时使用提交 SHA，则可以确保重用该工作流的每个人都将始终使用相同的 YAML 代码。但是，如果通过标记或分支引用可重用工作流程，请确保您可以信任该版本的工作流程。有关详细信息，请参阅“GitHub Actions 的安全强化”。

有关详细信息，请参阅“为组织创建入门工作流程”。

访问可重复使用的工作流程

如果满足以下任意条件，则可重用工作流程可由另一个工作流使用：

这两个工作流程位于同一存储库中。
调用的工作流存储在公共存储库中。
被调用的工作流程存储在内部存储库中，该存储库的设置允许对其进行访问。有关详细信息，请参阅 “与企业共享操作和工作流””。

使用运行器

与调用方工作流程属于同一用户或组织或企业的被调用工作流程可以从调用方的上下文中访问自托管运行器。这意味着被调用的工作流程可以访问自托管运行器，这些运行器具有以下特点：

在调用方存储库中
在调用方存储库的组织或企业中，前提是运行器已可供调用方存储库使用

限制

可重用工作流程无法调用其他可重用工作流程。
最多可以从单个工作流文件调用 20 个可重用工作流。
存储在专用存储库中的可重用工作流只能由同一存储库中的工作流使用。 * 调用可重用工作流的任何作业都不支持 strategy 属性。
对于在调用方工作流中的工作流级别定义的 env 上下文，在其中设置的任何环境变量都不会传播到被调用的工作流。有关详细信息，请参阅“变量”和“上下文”。
若要在多个工作流中重复使用变量，请在组织、存储库或环境级别设置变量，并使用 vars 上下文来引用它们。有关详细信息，请参阅“变量”和“上下文”。

创建可重用的工作流程

可重用工作流程是 YAML 格式的文件，与任何其他工作流程文件非常相似。与其他工作流文件一样，可以在存储库的 .github/workflows 目录中找到可重用的工作流。不支持 workflows 目录的子目录。

若要使工作流可重用，on 的值必须包括 workflow_call：

on:
  workflow_call:

在可重用工作流程中使用输入和机密

您可以定义输入和机密，这些输入和机密可以从调用方工作流程传递，然后在被调用的工作流程中使用。在可重用工作流程中使用输入或机密有三个阶段。

在可重用工作流中，使用 inputs 和 secrets 关键字定义将从调用方工作流传递的输入或机密。
```
on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      envPAT:
        required: true
```
有关定义输入和机密的语法的详细信息，请参阅 on.workflow_call.inputs 和 on.workflow_call.secrets。
在可重用工作流中，引用在上一步的 on 键中定义的输入或机密。

注意：如果在调用工作流中使用 secrets: inherit 继承机密，那么即使未在 on 键中显式定义机密，也可以引用它们。有关详细信息，请参阅“GitHub Actions 的工作流语法”。
```
jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    environment: production
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.envPAT }}
        configuration-path: ${{ inputs.config-path }}
```
在上面的示例中，envPAT 是已添加到 production 环境的环境机密。因此，在作业中引用了此环境。

注意：环境机密是存储在为存储库定义的环境中的加密字符串。环境机密仅适用于引用相应环境的工作流程作业。有关详细信息，请参阅“使用环境进行部署”。

传递来自调用方工作流程的输入或机密。

若要将命名输入传递到调用的工作流，请在作业中使用 with 关键字。使用 secrets 关键字传递命名机密。对于输入，输入值的数据类型必须与调用的工作流中指定的类型（布尔值、数字或字符串）匹配。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      envPAT: ${{ secrets.envPAT }}

在同一组织或企业中调用可重用工作流的工作流可使用 inherit 关键字隐式传递机密。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

示例可重用工作流程

此名为 workflow-B.yml 的可重用工作流文件（稍后将在调用方工作流示例中引用此文件）从调用方工作流中获取输入字符串和机密，并在操作中使用它们。

YAML

name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

调用可重用工作流程

使用 uses 关键字调用可重用工作流。与在工作流程中使用操作不同，您可以直接在作业中调用可重用工作流程，而不是从作业步骤中调用。

jobs.<job_id>.uses

可以使用以下语法之一：

{owner}/{repo}/.github/workflows/{filename}@{ref} 用于公共和内部存储库中的可重用工作流。
./.github/workflows/{filename} 用于同一存储库中的可重用工作流。

{ref} 可以是 SHA、发布标记或分支名称。对于稳定性和安全性来说，使用提交 SHA 最稳妥。有关详细信息，请参阅“GitHub Actions 的安全强化”。如果使用第二个语法选项（不带 {owner}/{repo} 和 @{ref}），则调用的工作流来自与调用方工作流相同的提交。

您可以调用多个工作流程，在单独的作业中引用每个工作流程。

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

将输入和机密传递到可重用的工作流程

若要将命名输入传递到调用的工作流，请在作业中使用 with 关键字。使用 secrets 关键字传递命名机密。对于输入，输入值的数据类型必须与调用的工作流中指定的类型（布尔值、数字或字符串）匹配。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      envPAT: ${{ secrets.envPAT }}

在同一组织或企业中调用可重用工作流的工作流可使用 inherit 关键字隐式传递机密。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

调用可重用工作流程的作业支持的关键字

调用可重用工作流程时，只能在包含调用的作业中使用以下关键字：

jobs.<job_id>.name
jobs.<job_id>.uses
jobs.<job_id>.with
jobs.<job_id>.with.<input_id>
jobs.<job_id>.secrets
jobs.<job_id>.secrets.<secret_id>
jobs.<job_id>.secrets.inherit
jobs.<job_id>.needs
jobs.<job_id>.if
jobs.<job_id>.permissions
jobs.<job_id>.concurrency
注意：
- 如果调用作业中未指定 jobs.<job_id>.permissions，则调用的工作流将具有 GITHUB_TOKEN 的默认权限。有关详细信息，请参阅“自动令牌身份验证”。
- 从调用方工作流传递的 GITHUB_TOKEN 权限只能由被调用的工作流降级（不能升级）。

示例调用方工作流程

此工作流程文件调用两个工作流程文件。向其中的第二个文件 workflow-B.yml（如可重用工作流示例中所示）传递了一个输入 (config-path) 和一个机密 (token)。

YAML

name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    permissions:
      contents: read
      pull-requests: write
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

使用可重用工作流程的输出

可重用工作流程可能会生成要在调用方工作流程中使用的数据。若要使用这些输出，必须将它们指定为可重用工作流的输出。

以下可重用工作流程具有包含两个步骤的单个作业。在每个步骤中，我们设置一个单词作为输出："hello" 和 "world"。在作业的 outputs 部分，我们将这些步骤输出映射到名为 output1 和 output2 的作业输出。然后，在 on.workflow_call.outputs 部分中，为工作流本身定义两个输出，一个称为 firstword，映射到 output1，另一个称为 secondword，映射到 output2。

YAML

name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

现在，我们可以在调用方工作流程中使用输出，就像使用同一工作流程中作业的输出一样。我们使用在可重用工作流中的工作流级别定义的名称引用输出：firstword 和 secondword。在此工作流中，job1 调用可重用工作流，job2 将可重用工作流的输出（“hello world”）呈现在工作流日志的标准输出中。

YAML

name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

有关使用作业输出的详细信息，请参阅“GitHub Actions 的工作流语法”。

监控正在使用的工作流程

您可以使用 GitHub REST API 来监控可重用工作流程的使用过程。 prepared_workflow_job 审核日志操作会在工作流作业启动时触发。记录的数据包括：

repo - 工作流作业所在的组织/存储库。对于调用其他工作流程的作业，这是调用方工作流程的组织/存储库。
@timestamp - 启动作业的日期和时间，采用 Unix 纪元格式。
job_name - 运行的作业的名称。
job_workflow_ref - 使用的工作流文件，采用 {owner}/{repo}/{path}/{filename}@{ref} 格式。对于调用其他工作流程的作业，这用于标识被调用的工作流程。

有关使用 REST API 查询组织的审核日志的信息，请参阅“组织”。

注意：只能使用 REST API 查看 prepared_workflow_job 的审核数据。它在 GitHub Web 界面中不可见，也不包含在 JSON/CSV 导出的审核数据中。

使用可重用工作流重新运行工作流和作业

可使用 SHA、发布标记或分支名称引用公共存储库中的可重用工作流。有关详细信息，请参阅“重新使用工作流”。

重新运行使用可重用工作流且引用不是 SHA 的工作流时，有一些行为需要注意：

重新运行工作流中的所有作业时将使用指定引用中的可重用工作流。若要详细了解如何重新运行工作流中的所有作业，请参阅“重新运行工作流程和作业”。
重新运行失败的作业或工作流中的特定作业时将使用第一次尝试的同一提交 SHA 中的可重用工作流。若要详细了解如何重新运行工作流中失败的作业，请参阅“重新运行工作流程和作业”。若要详细了解如何重新运行工作流中的特定作业，请参阅“重新运行工作流程和作业”。

后续步骤

若要继续了解 GitHub Actions，请参阅“触发工作流的事件”。

你可以通过创建只能执行特定可重用工作流的自托管运行器组来标准化部署。有关详细信息，请参阅“使用组管理对自托管运行程序的访问”。

重新使用工作流

本文内容