GitHub Actions：创建和调用可重用工作流-未完纪

把多个工作流中重复的任务提取到一个可重用工作流，可以统一维护输入、机密、权限和输出。调用方通过作业级 uses 引用它；被调用方用 workflow_call 声明可以接受的接口。

创建可重用的工作流

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

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

on:
  workflow_call:

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

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

在可重用工作流中，使用 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 。

在可重用工作流中，引用在上一步的 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 的工作流语法。

传递来自调用方工作流的输入或机密。
若要将命名输入传递到调用的工作流，请在作业中使用 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 的可重用工作流文件（稍后将在调用方工作流示例中引用此文件）从调用方工作流中获取输入字符串和机密，并在操作中使用它们。

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

可以使用以下语法之一引用可重用的工作流文件：

$/.github/workflows/{filename}：引用同一仓库中的可重用工作流。这是同仓库引用的推荐语法，但 GitHub Enterprise Server 不支持这一语法。
{owner}/{repo}/.github/workflows/{filename}@{ref}：引用公共或私有仓库中的可重用工作流。
./.github/workflows/{filename}：引用同一仓库中的可重用工作流。
使用 {owner}/{repo} 和 @{ref} 引用工作流时，{ref} 可以是提交 SHA、发布标签或分支名。如果标签与分支同名，发布标签优先。为保持稳定性和安全性，固定到提交 SHA 是最稳妥的选择。更多信息见 GitHub 的安全使用参考。

使用 $/ 或 ./ 引用同一仓库中的可重用工作流时，不带 {owner}/{repo} 和 @{ref}，被调用工作流与调用方来自同一次提交。$/ 引用不得带 @{ref} 后缀，而且 GitHub Enterprise Server 不支持 $/。不允许 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
  # The `$/` syntax is not available in GitHub Enterprise Server.
  call-workflow-in-same-repo-at-running-commit:
    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)。

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] 来引用矩阵上下文。它将运行三个作业，变量中的每个值对应一个作业。

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 → … → called-workflow-9.yml。

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

注意

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

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

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 的工作流语法。

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”）呈现在工作流日志的标准输出中。

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 的工作流语法。如果要在工作流之间共享变量以外的内容（例如生成工件），请参阅使用工作流工件存储和共享数据。

控制可重用工作流中的缓存访问

可以使用 cache-mode 关键字，授予可重用工作流所需的最少 GitHub Actions 缓存访问权限。值可以是 read、write、write-only 或 none。省略 cache-mode 时，将根据触发器类型默认采用 read 或 write。完整语法、每个值的含义见工作流语法文档；触发器相关默认值见依赖缓存参考。

当调用方工作流调用可重用工作流时， cache-mode 将传播到调用的工作流。调用作业上的或从调用方工作流继承的显式 cache-mode，会限制被调用工作流可以请求的缓存访问权限。

如果调用作业既不设置也不继承显式cache-mode，即使调用方低信任触发器默认为 read，调用的工作流也可以显式请求write。若要将调用的工作流上限设置为只读访问权限，请在调用它的作业上设置 cache-mode: read 。
如果被调用工作流声明的 cache-mode 请求超出上述显式上限，运行不会启动，GitHub 会报告验证错误。例如，最多允许 read 的调用方不能调用声明 write 的工作流。read 授予恢复缓存的权限，write-only 授予保存缓存的权限，两者并不重叠，因此相互不匹配也属于超出权限请求；例如，write-only 调用方不能调用声明 read 的工作流。

有关缓存访问和四种模式的详细信息，请参阅依赖项缓存参考。

监控正在使用的工作流

使用 GitHub Enterprise Cloud 的组织可以通过 REST API 与审核日志 GitHub 进行交互，以监视正在使用的工作流。有关详细信息，请参阅GitHub Enterprise Cloud文档。

后续步骤

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

示例范围与来源许可

本页保留官方页面的全部 16 个不同用途的 YAML 示例。同一页面的重复代码展示合并为一次，代码之外的网页转录反引号已移除，代码中的动作版本、表达式、机密变量名称和注释保留原样。示例中的仓库、路径和标签需要替换为实际可访问且可信的工作流；机密引用是变量名称，没有在此读取或公开机密。本次没有运行 GitHub Actions，也没有验证任何示例仓库的部署结果。

修改日期：2026-10-03。修改内容：整理官方中文全文、统一“工作流”用语、修复网页转录的重复 YAML 和乱码，并根据英文原文核对同仓库引用语法、十级嵌套上限及四种缓存权限模式。此稿是已有中文文档的整理，不是新翻译。

代码许可全文如下：

MIT License

Copyright 2026 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

文章版权归作者所有，未经允许请勿转载。

THE END