重用工作流配置

可重用工作流

可重用工作流的参考信息。

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

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

这两个工作流程位于同一存储库中。
被调用的工作流存储在 GitHub Enterprise Server 上的公共存储库中。

不能直接使用在 GitHub.com 上定义的可重用工作流。相反，将可重用工作流的副本存储在你的 GitHub Enterprise Server 实例上，并从该路径调用工作流。
被调用的工作流程存储在内部存储库中，该存储库的设置允许对其进行访问。有关详细信息，请参阅“与企业共享操作和工作流”。
被调用的工作流存储在专用存储库中，该存储库的设置允许对其进行访问。有关详细信息，请参阅与企业共享操作和工作流。

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

调用方存储库	可访问的工作流存储库
`private`	`private`、`internal`、以及 `public`
`internal`	`internal`，且 `public`
`public`	`public`

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

对于内部存储库或专用存储库，必须在所调用工作流存储库的“操作设置”页面上将访问策略显式配置为允许从包含调用方工作流的存储库进行访问 - 请参阅“管理存储库的 GitHub Actions 设置”。

注意

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

可重用工作流的限制

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

例如，top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml 计为 2 个可重用工作流。
对于在调用方工作流中的工作流级别定义的 env 上下文，在其中设置的任何环境变量都不会传播到被调用的工作流。有关详细信息，请参阅在变量中存储信息和上下文参考。
同样，对于在被调用的工作流中定义的 env 上下文，无法在调用方工作流的 env 上下文中访问在其中设置的环境变量。必须改用可重用工作流的输出。有关详细信息，请参阅“使用可重用工作流的输出”。
若要在多个工作流中重复使用变量，请在组织、存储库或环境级别设置变量，并使用 vars 上下文来引用它们。有关详细信息，请参阅“在变量中存储信息”和“上下文参考”。
可重用工作流直接在作业中调用，而不是从作业步骤中调用。因此，不能使用 GITHUB_ENV 将值传递给调用方工作流中的作业步骤。

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

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

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 Actions 的工作流语法”。
- 从调用方工作流传递的 GITHUB_TOKEN 权限只能由被调用的工作流降级（不能升级）。
- 如果使用 jobs.<job_id>.concurrency.cancel-in-progress: true，请不要在调用工作流和调用方工作流中使用相同的 jobs.<job_id>.concurrency.group 值，因为这将导致已运行的工作流被取消。调用的工作流在 ${{ github.workflow }} 中使用其调用方工作流的名称，因此使用此上下文作为调用方工作流和调用工作流的 jobs.<job_id>.concurrency.group 值将导致调用方工作流在调用工作流运行时被取消。

可重用工作流程如何使用运行器

GitHub 托管的运行器

始终仅使用调用方的上下文来评估 GitHub 托管的运行器的分配。 GitHub 托管的运行器的计费始终与调用方相关联。调用方工作流程不能使用被调用存储库中 GitHub 托管的运行器。有关详细信息，请参阅“GitHub 托管的运行程序”。

自托管运行程序

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

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

嵌套工作流程的访问权限和权限

如果初始调用方工作流无法访问任何嵌套工作流，则包含嵌套可重用工作流的工作流会失败。有关详细信息，请参阅可重用工作流程的访问权限。

GITHUB_TOKEN 权限在嵌套工作流中只能相同或更严格。例如，在工作流链 A > B > C 中，如果工作流 A 具有 package: read 令牌权限，则 B 和 C 不能具有 package: write 权限。有关详细信息，请参阅“在工作流中使用 GITHUB_TOKEN 进行身份验证”。

有关如何使用 API 确定特定工作流运行中涉及哪些工作流文件的信息，请参阅重用工作流。

重新运行作业时可重用工作流程的行为

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

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

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

`github` 上下文

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

工作流模板

为组织创建工作流模板时要使用的参考信息。

工作流模板可用性

可以在匹配的存储库或受限可见性高于模板存储库的存储库中使用模板。

公共 .github 存储库中的工作流模板可用于所有存储库类型。
内部 .github 存储库中的工作流模板仅适用于内部和专用存储库。
专用 .github 存储库中的工作流模板仅适用于专用存储库。

授予专用/内部存储库的访问权限

如果使用专用或内部 .github 存储库，则需要向应该能够使用模板的用户或团队授予读取访问权限。

`$default-branch` 占位符

如果需要引用存储库的默认分支，可以在工作流模板中使用 $default-branch 占位符。创建工作流程时，占位符将自动替换为仓库默认分支的名称。

`runs-on` 键中的占位符值

runs-on 键中的以下值也被视为占位符：

ubuntu-latest 替换为 [ self-hosted ]
windows-latest 替换为 [ self-hosted, windows ]
macos-latest" 替换为 [ self-hosted, macOS ]

示例工作流模板文件

此文件名为 octo-organization-ci.yml，用于演示基本工作流。

YAML

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run a one-line script
        run: echo Hello from Octo Organization

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run a one-line script
        run: echo Hello from Octo Organization

元数据文件要求

元数据文件必须与工作流程文件同名，但扩展名不是 .yml，而必须附加 .properties.json。例如，名为 octo-organization-ci.properties.json 的文件包含名为 octo-organization-ci.yml 的工作流文件的元数据：

JSON

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

name - 必选。 工作流的名称。这会显示在可用工作流程列表中。
description - 必选。 工作流的说明。这会显示在可用工作流程列表中。
iconName - 可选。 指定工作流列表中显示的工作流图标。 iconName 可以是以下类型之一：
- 存储在 workflow-templates 目录中的 SVG 文件。若要引用文件，该值必须是不带文件扩展名的文件名。例如，名为 example-icon.svg 的 SVG 文件被引用为 example-icon。
- 来自 GitHub 的 Octicons 集的图标。若要引用 octicon，该值必须为 octicon <icon name>。例如 octicon smiley。
categories - 可选。 定义用于显示工作流的类别。可以使用以下列表中的类别名称：
- starter-workflows 存储库中的一般类别名称。
- linguist 存储库列表中的 linguist 语言。
- starter-workflows 存储库的列表中支持的技术堆栈。
filePatterns - 可选。 如果用户的存储库在其根目录中具有与定义的正则表达式匹配的文件，则允许使用工作流。

本文内容