重复使用工作流程 - GitHub 文档

概述

无需在工作流之间复制粘贴，您可以使工作流可重用。您和任何有权访问可重用工作流的人都可以从另一个工作流中调用可重用工作流。

重用工作流避免了重复。这使得工作流更易于维护，并允许您通过利用他人的工作成果更快地创建新的工作流，就像您使用操作一样。工作流重用还通过帮助您使用设计良好、已经过测试并已被证明有效的工作流来促进最佳实践。您的组织可以建立一个可集中维护的可重用工作流库。

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

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

Diagram of a workflow calling a reusable workflow.

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

如果您重用来自不同存储库的工作流，则被调用工作流中的任何操作都将像它们是调用者工作流的一部分一样运行。例如，如果被调用工作流使用actions/checkout，则该操作将检出托管调用者工作流的存储库的内容，而不是被调用工作流。

当可重用工作流由调用者工作流触发时，github上下文始终与调用者工作流相关联。被调用工作流会自动获得对github.token和secrets.GITHUB_TOKEN的访问权限。有关github上下文的更多信息，请参阅“访问有关工作流运行的上下文信息”。

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

可重用工作流和复合操作

可重用工作流和复合操作都可以帮助您避免重复。可重用工作流允许您重用整个工作流（包含多个作业和步骤），而复合操作则组合多个步骤，然后您可以在作业步骤中运行这些步骤，就像任何其他操作一样。有关更多信息，请参阅“避免重复”。

工作流模板允许组织中任何有权创建工作流的人员更快、更轻松地创建工作流。当人们创建新的工作流时，他们可以选择工作流模板，这样编写工作流的部分或全部工作将由系统完成。在工作流模板中，您还可以引用可重用工作流，以便人们可以轻松地从重用集中管理的工作流代码中受益。如果您在引用可重用工作流时使用提交 SHA，则可以确保所有重用该工作流的人员始终使用相同的 YAML 代码。但是，如果您通过标签或分支引用可重用工作流，请确保您可以信任该版本的工作流。有关更多信息，请参阅“GitHub Actions 的安全强化”。

有关更多信息，请参阅“为您的组织创建工作流模板”。

访问可重用工作流

如果满足以下任何条件，另一个工作流可以使用可重用工作流

两个工作流都在同一个存储库中。
被调用工作流存储在公共存储库中，并且您的组织允许您使用公共可重用工作流。
被调用工作流存储在私有存储库中，并且该存储库的设置允许访问它。有关更多信息，请参阅“与您的组织共享操作和工作流”和“从您的私有存储库共享操作和工作流”。

下表显示了可重用工作流对调用者工作流的可访问性，具体取决于主机存储库的可见性。

调用者存储库	可访问的工作流存储库
`私有`	`私有`和`公共`
`公共`	`公共`

调用者存储库的 Actions 设置页面上的**Actions 权限**必须配置为允许使用操作和可重用工作流 - 请参阅“管理存储库的 GitHub Actions 设置”。

对于私有存储库，必须在被调用工作流存储库的 Actions 设置页面上明确配置**访问**策略，以允许从包含调用者工作流的存储库进行访问 - 请参阅“管理存储库的 GitHub Actions 设置”。

注意

为了增强安全性，GitHub Actions 不支持操作或可重用工作流的重定向。这意味着当操作的存储库所有者、名称或操作名称更改时，使用先前名称使用该操作的任何工作流都将失败。

使用运行器

使用 GitHub 托管的运行器

GitHub 托管运行器的分配始终仅使用调用者的上下文进行评估。GitHub 托管运行器的计费始终与调用者相关联。调用者工作流无法使用被调用存储库中的 GitHub 托管运行器。有关更多信息，请参阅“使用 GitHub 托管的运行器”。

使用自托管运行器

与调用者工作流属于同一用户或组织的被调用工作流可以访问调用者上下文中的自托管运行器。这意味着被调用工作流可以访问以下自托管运行器：

在调用者存储库中
在调用者存储库的组织中，前提是该运行器已提供给调用者存储库

限制

您可以连接最多四层工作流。有关更多信息，请参阅“嵌套可重用工作流”。
您可以从单个工作流文件中最多调用 20 个唯一可重用工作流。此限制包括从顶级调用者工作流文件开始可能调用的任何嵌套可重用工作流树。

例如，顶级调用者工作流.yml → 被调用工作流-1.yml → 被调用工作流-2.yml 计为 2 个可重用工作流。
在调用者工作流的工作流级别定义的env上下文中设置的任何环境变量都不会传播到被调用工作流。有关更多信息，请参阅“在变量中存储信息”和“访问有关工作流运行的上下文信息”。
同样，在被调用工作流中定义的env上下文中设置的环境变量在调用者工作流的env上下文中不可访问。相反，您必须使用可重用工作流的输出。有关更多信息，请参阅“使用可重用工作流的输出”。
要在多个工作流中重用变量，请在组织、存储库或环境级别设置它们，并使用vars上下文引用它们。有关更多信息，请参阅“在变量中存储信息”和“访问有关工作流运行的上下文信息”。
可重用工作流直接在作业中调用，而不是在作业步骤中调用。因此，您不能使用GITHUB_ENV将值传递给调用者工作流中的作业步骤。

创建可重用工作流

可重用工作流是 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@v4
      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的可重用工作流文件（我们将在后面的示例调用工作流中提到它）接收来自调用工作流的输入字符串和密钥，并在操作中使用它们。

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 }}

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}），则调用的工作流与调用工作流来自相同的提交。不允许使用refs/heads和refs/tags等 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

将输入和密钥传递给可重用工作流

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

使用矩阵策略和可重用工作流

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

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

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

YAML

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

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

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

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

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>.strategy
jobs.<job_id>.needs
jobs.<job_id>.if
jobs.<job_id>.concurrency
jobs.<job_id>.permissions
注意
- 如果在调用作业中未指定jobs.<job_id>.permissions，则调用的工作流将具有GITHUB_TOKEN的默认权限。更多信息，请参见“自动令牌身份验证”。
- 从调用工作流传递的GITHUB_TOKEN权限只能被调用的工作流降低（不能提升）。
- 如果您使用jobs.<job_id>.concurrency.cancel-in-progress: true，请不要在被调用和调用工作流中使用相同的jobs.<job_id>.concurrency.group值，因为这将导致正在运行的工作流被取消。被调用工作流在其调用工作流中使用${{ github.workflow }}的名称，因此在调用和被调用工作流中都使用此上下文作为jobs.<job_id>.concurrency.group的值将导致调用工作流在被调用工作流运行时被取消。

示例调用工作流

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

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 }}

嵌套可重用工作流

您可以连接最多四层工作流——即顶级调用工作流和最多三层可重用工作流。例如：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

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 中，只有当密钥从 A 传递到 B，然后从 B 传递到 C 时，工作流 C 才能从 A 接收密钥。

在以下示例中，工作流 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

访问和权限

如果任何嵌套工作流都无法访问初始调用工作流，则包含嵌套可重用工作流的工作流将失败。更多信息，请参见“重用工作流”。

GITHUB_TOKEN权限在嵌套工作流中只能保持相同或更严格。例如，在工作流链 A > B > C 中，如果工作流 A 具有package: read令牌权限，则 B 和 C 不能具有package: write权限。更多信息，请参见“自动令牌身份验证”。

有关如何使用 API 确定哪些工作流文件参与特定工作流运行的信息，请参见“监控正在使用的哪些工作流”。

使用可重用工作流的输出

可重用工作流可能会生成您希望在调用工作流中使用的数据。要使用这些输出，必须将其指定为可重用工作流的输出。

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

以下可重用工作流具有一个包含两个步骤的作业。在这些步骤中的每个步骤中，我们设置一个单词作为输出：“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

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 }}

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 - 已运行作业的名称。
calling_workflow_refs - 一个包含参与此工作流作业的所有调用者工作流的文件路径数组。数组中的项目按照它们被调用的反向顺序排列。例如，在工作流 A > B > C 的链中，当查看工作流 C 中作业的日志时，数组将为 ["octo-org/octo-repo/.github/workflows/B.yml", "octo-org/octo-repo/.github/workflows/A.yml"]。
calling_workflow_shas - 一个包含参与此工作流作业的所有调用者工作流的 SHA 值的数组。该数组包含与 calling_workflow_refs 数组相同数量的项目，顺序也相同。
job_workflow_ref - 使用的工作流文件，格式为 {owner}/{repo}/{path}/{filename}@{ref}。对于调用另一个工作流的作业，这将标识被调用的工作流。

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

注意

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

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

可以使用 SHA、发行版标签或分支名称引用来自公共存储库的可重用工作流。有关更多信息，请参阅“重用工作流”。

重新运行使用可重用工作流的工作流时，如果引用不是 SHA，则需要注意一些行为。

重新运行工作流中的所有作业将使用指定引用中的可重用工作流。有关重新运行工作流中所有作业的更多信息，请参阅“重新运行工作流和作业”。
重新运行工作流中失败的作业或特定作业将使用第一次尝试的相同提交 SHA 的可重用工作流。有关重新运行工作流中失败作业的更多信息，请参阅“重新运行工作流和作业”。有关重新运行工作流中特定作业的更多信息，请参阅“重新运行工作流和作业”。

后续步骤

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

重用工作流

开始使用 GitHub Actions

本文内容

概述

可重用工作流和复合操作

可重用工作流和工作流模板

访问可重用工作流

使用运行器

使用 GitHub 托管的运行器

使用自托管运行器

限制

创建可重用工作流

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

示例可重用工作流

调用可重用工作流

将输入和密钥传递给可重用工作流

使用矩阵策略和可重用工作流

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

示例调用工作流

嵌套可重用工作流

将密钥传递给嵌套工作流

访问和权限

使用可重用工作流的输出

监控正在使用的哪些工作流

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

后续步骤