重用工作流

了解如何通过重用现有工作流程来避免在创建工作流程时重复。

在本文中

创建可重用的工作流程

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

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

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

on:
  workflow_call:

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

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

  1. 在可重用工作流中，使用 inputs 和 secrets 关键字定义将从调用方工作流传递的输入或机密。

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

    有关定义输入和机密的语法的详细信息，请参阅 on.workflow_call.inputs 和 on.workflow_call.secrets。

  2. 在可重用工作流中，引用在上一步的 on 键中定义的输入或机密。

    注意

    如果在调用工作流中使用 secrets: inherit 继承机密，那么即使未在 on 键中显式定义机密，也可以引用它们。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。

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

    在上面的示例中，personal_access_token 是在存储库或组织级别定义的机密。

    警告

    无法从调用方工作流传递环境机密，因为 on.workflow_call 不支持 environment 关键字。 如果在作业级别的可重用工作流中包含 environment，则将使用环境机密，而不是从调用方工作流传递的机密。 有关详细信息，请参阅 管理部署环境 和 GitHub Actions 的工作流语法。

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

    若要将命名输入传递到调用的工作流，请在作业中使用 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:
      personal_access_token: ${{ secrets.token }}

    在同一组织或企业中调用可重用工作流的工作流可以使用 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@v6
      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 是最稳妥的选项。 有关详细信息，请参阅“安全使用指南”。

如果使用第二个语法选项（不带 {owner}/{repo} 和 @{ref}），则调用的工作流来自与调用方工作流相同的提交。 不允许使用 refs/heads 和 refs/tags 等引用前缀。 您不能在此关键词中使用上下文或表达式。

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

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

示例调用方工作流程

此工作流程文件调用两个工作流程文件。 向其中的第二个文件 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 }}

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

若要将命名输入传递到调用的工作流，请在作业中使用 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:
      personal_access_token: ${{ secrets.token }}

在同一组织或企业中调用可重用工作流的工作流可以使用 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

将矩阵策略与可重用工作流配合使用

使用矩阵策略的作业可以调用可重用工作流。

使用矩阵策略，可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。 例如，可以使用矩阵策略将不同输入传递给可重用工作流。 有关矩阵的详细信息，请参阅“在工作流中运行作业变体”。

以下示例作业调用可重用工作流，并通过使用值 target 定义变量 [dev, stage, prod] 来引用矩阵上下文。 它将运行三个作业，变量中的每个值对应一个作业。

YAML
jobs:
  ReusableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

嵌套可重用工作流

最多可以连接 四个工作流级别 - 即顶级调用方工作流和最多三个级别的可重用工作流。 例如：caller-workflow.yml__→called-workflow-1.yml_→_called-workflow-2.yml→__called-workflow-3.yml。

不允许工作流树中存在循环。

注意

嵌套的可重用工作流要求链中的所有工作流都可供调用方访问，并且在整个链中，权限只能保持不变或降低，而不能提升。 有关详细信息，请参阅“重用工作流配置”。

在可重用工作流中，可以调用另一个可重用工作流。

YAML
name: Reusable workflow

on:
  workflow_call:

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

将机密传递给嵌套工作流

可以在调用工作流中使用 jobs.<job_id>.secrets 将命名机密传递给直接调用的工作流。 或者，可以使用 jobs.<job_id>.secrets.inherit 将调用工作流的所有机密传递给直接调用的工作流。 有关详细信息，请参阅上面的 重用工作流 部分和参考文章 GitHub Actions 的工作流语法。 机密仅传递给直接调用的工作流，因此在工作流链 A > B > C 中，工作流 C 仅从 A 接收从 A 传递给 B，然后从 B 传递给 C 的机密。

在以下示例中，工作流 A 使用 inherit 关键字将其所有机密传递给工作流 B，但工作流 B 仅将一个机密传递给工作流 C。传递给工作流 B 的任何其他机密都不可供工作流 C 使用。

jobs:
  workflowA-calls-workflowB:
    uses: octo-org/example-repo/.github/workflows/B.yml@main
    secrets: inherit # pass all secrets

jobs:
  workflowB-calls-workflowC:
    uses: different-org/example-repo/.github/workflows/C.yml@main
    secrets:
      repo-token: ${{ secrets.personal_access_token }} # pass just this secret

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

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

如果设置输出的可重用工作流使用矩阵策略来执行，则输出会是由矩阵的最后一个成功完成且实际设置值的可重用工作流设置的输出。 这意味着，如果最后一个成功完成可重用工作流为其输出设置空字符串，而倒数第二个成功完成可重用工作流为其输出设置实际值，则输出会包含倒数第二个完成可重用工作流的值。

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

必须将 value 设置为所调用工作流中作业级输出的值。 步骤级输出必须首先映射到作业级输出，如下所示。

有关详细信息，请参阅 在作业之间传递信息 和 GitHub Actions 的工作流语法。

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 "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

现在，我们可以在调用方工作流程中使用输出，就像使用同一工作流程中作业的输出一样。 我们使用在可重用工作流中的工作流级别定义的名称引用输出：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 Enterprise Cloud 的组织可以通过 GitHub REST API 与审核日志进行交互，以监视正在使用的工作流。 有关详细信息，请参阅 GitHub Enterprise Cloud 文档。

后续步骤

要查找有关工作流重用细节的信息，请参阅 重用工作流配置。