重用工作流配置

通过重用现有工作流以及使用 YAML 定位点和别名，查找有关在创建工作流时避免重复的信息。

本文内容

可重用工作流

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

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

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

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

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

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

调用方存储库的“操作设置”页面上的“操作权限”必须配置为允许使用操作和可重用工作流 - 请参阅“管理存储库的 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 将值传递给调用方工作流中的作业步骤。

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

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

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

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 存储库，因此它们不适用于 Enterprise Managed Users。

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

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

$default-branch 占位符

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

示例工作流模板文件

此文件名为 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@v5
      - 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 - 必选。 工作流的名称。 这会显示在可用工作流程列表中。

  • description - 必选。 工作流的说明。 这会显示在可用工作流程列表中。

  • iconName - 可选。 指定工作流列表中显示的工作流图标。 iconName 可以是以下类型之一：

    • 存储在 workflow-templates 目录中的 SVG 文件。 若要引用文件，该值必须是不带文件扩展名的文件名。 例如，名为 example-icon.svg 的 SVG 文件被引用为 example-icon。
    • 来自 GitHub 的 Octicons 集的图标。 若要引用 octicon，该值必须为 octicon <icon name>。 例如 octicon smiley。

  • categories - 可选。 定义用于显示工作流的类别。 可以使用以下列表中的类别名称：

  • filePatterns - 可选。 如果用户的存储库在其根目录中具有与定义的正则表达式匹配的文件，则允许使用工作流。

YAML 定位点和别名

可以使用 YAML 定位点和别名来减少工作流中的重复。 定位点（标记为 &）标识要重用的内容，而别名（标记为 *）在另一个位置重复该内容。

有关定位点和别名的详细信息，请参阅 YAML 规范中的节点定位点和别名。

下面是将 YAML 定位点和别名与环境变量配合使用的示例：

jobs:
  job1:
    env: &env_vars # Define the anchor on first use
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Using production settings"

  job2:
    env: *env_vars # Reuse the environment variables
    steps:
      - run: echo "Same environment variables here"

这相当于在没有定位点和别名的情况下编写以下 YAML：

jobs:
  job1:
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Using production settings"

  job2:
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Same environment variables here"

还可以将定位点用于更复杂的配置，例如重用整个作业配置：

jobs:
  test: &base_job # Define the anchor on first use
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      NODE_VERSION: '18'
    steps:
      - uses: actions/checkout@v5
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm test

  alt-test: *base_job # Reuse the entire job configuration