{"meta":{"title":"重用工作流配置","intro":"通过重用现有工作流和使用 YAML 定位点和别名查找有关在创建工作流时避免重复的信息。","product":"GitHub Actions","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/actions","title":"GitHub Actions"},{"href":"/zh/enterprise-cloud@latest/actions/reference","title":"参考"},{"href":"/zh/enterprise-cloud@latest/actions/reference/workflows-and-actions","title":"工作流和操作"},{"href":"/zh/enterprise-cloud@latest/actions/reference/workflows-and-actions/reusing-workflow-configurations","title":"重用工作流配置"}],"documentType":"article"},"body":"# 重用工作流配置\n\n通过重用现有工作流和使用 YAML 定位点和别名时避免重复的信息。\n\n## 可重用工作流\n\n可重用工作流的参考信息。\n\n### 访问可重复使用的工作流程\n\n如果满足以下任意条件，则可重用工作流程可由另一个工作流使用：\n\n* 这两个工作流程位于同一存储库中。\n* 调用的工作流存储在公共存储库，企业允许你使用公共可重用工作流。\n* 被调用的工作流程存储在内部存储库中，该存储库的设置允许对其进行访问。 有关详细信息，请参阅 [与企业共享操作和工作流](/zh/enterprise-cloud@latest/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise)。\n* 被调用的工作流存储在专用存储库中，该存储库的设置允许对其进行访问。 有关详细信息，请参阅 [与企业共享操作和工作流](/zh/enterprise-cloud@latest/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise)。\n\n下表显示了可重用工作流对调用方工作流的可访问性，具体取决于主机存储库的可见性。\n\n| 调用方存储库                | 可访问的工作流存储库 |\n| --------------------- | ---------- |\n| `private`             |            |\n| `private`             |            |\n| 、`internal`和`public`  |            |\n|                       |            |\n| `internal`            |            |\n| `internal` 和 `public` |            |\n|                       |            |\n| `public`              | `public`   |\n\n调用方存储库的“操作设置”页面上的**操作权限**必须配置为允许使用操作和可重用工作流 - 请参阅 [管理存储库的GitHub Actions设置](/zh/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-select-actions-and-reusable-workflows-to-run)。\n\n对于 内部存储库或 专用存储库，必须显式配置调用工作流存储库的“操作设置”页上 **的访问策略，** 以允许从包含调用方工作流的存储库进行访问 - 请参阅 [管理存储库的GitHub Actions设置](/zh/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository)。\n\n> \\[!NOTE]\n> 为了增强安全性，GitHub Actions 不支持对操作或可重用工作流进行重定向。 这意味着，当所有者、操作存储库的名称或操作名称发生更改时，使用该操作并具有先前名称的任何工作流都将失败。\n\n### 可重用工作流的限制\n\n* 最多可以连接 十 个级别的工作流。 有关详细信息，请参阅“[嵌套可重用工作流](/zh/enterprise-cloud@latest/actions/how-tos/sharing-automations/reuse-workflows#nesting-reusable-workflows)”。\n\n* 可以从单个工作流文件调用最多 50 个唯一可重用工作流。 此限制包括可能从顶层调用方工作流文件开始调用的任何嵌套可重用工作流树。\n\n  例如，*top-level-caller-workflow\\.yml* → *called-workflow-1.yml* → *called-workflow-2.yml* 计为 2 个可重用工作流。\n\n* 对于在调用方工作流中的工作流级别定义的 `env` 上下文，在其中设置的任何环境变量都不会传播到被调用的工作流。 有关详细信息，请参阅 [在变量中存储信息](/zh/enterprise-cloud@latest/actions/learn-github-actions/variables) 和 [上下文参考](/zh/enterprise-cloud@latest/actions/learn-github-actions/contexts#env-context)。\n\n* 同样，对于在被调用的工作流中定义的 `env` 上下文，无法在调用方工作流的 `env` 上下文中访问在其中设置的环境变量。 必须改用可重用工作流的输出。 有关详细信息，请参阅“[使用可重用工作流的输出](/zh/enterprise-cloud@latest/actions/how-tos/sharing-automations/reuse-workflows#using-outputs-from-a-reusable-workflow)”。\n\n* 若要在多个工作流中重复使用变量，请在组织、存储库或环境级别设置变量，并使用 `vars` 上下文来引用它们。 有关详细信息，请参阅 [在变量中存储信息](/zh/enterprise-cloud@latest/actions/learn-github-actions/variables) 和 [上下文参考](/zh/enterprise-cloud@latest/actions/learn-github-actions/contexts#vars-context)。\n\n* 可重用工作流直接在作业中调用，而不是从作业步骤中调用。 因此，不能使用 `GITHUB_ENV` 将值传递给调用方工作流中的作业步骤。\n\n### 调用可重用工作流程的作业支持的关键字\n\n调用可重用工作流程时，只能在包含调用的作业中使用以下关键字：\n\n* [`jobs.<job_id>.name`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname)\n* [`jobs.<job_id>.uses`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iduses)\n* [`jobs.<job_id>.with`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idwith)\n* [`jobs.<job_id>.with.<input_id>`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idwithinput_id)\n* [`jobs.<job_id>.secrets`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecrets)\n* [`jobs.<job_id>.secrets.<secret_id>`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecretssecret_id)\n* [`jobs.<job_id>.secrets.inherit`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecretsinherit)\n* [`jobs.<job_id>.strategy`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategy)\n* [`jobs.<job_id>.needs`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds)\n* [`jobs.<job_id>.if`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif)\n* [`jobs.<job_id>.concurrency`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idconcurrency)\n* [`jobs.<job_id>.permissions`](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions)\n\n  > \\[!NOTE]\n  >\n  > * 如果调用作业中未指定 `jobs.<job_id>.permissions`，则调用的工作流将具有 `GITHUB_TOKEN` 的默认权限。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/enterprise-cloud@latest/actions/reference/workflow-syntax-for-github-actions#permissions)”。\n  > * 从调用方工作流传递的 `GITHUB_TOKEN` 权限只能由被调用的工作流降级（不能升级）。\n  > * 如果使用 `jobs.<job_id>.concurrency.cancel-in-progress: true`，请不要在调用工作流和调用方工作流中使用相同的 `jobs.<job_id>.concurrency.group` 值，因为这将导致已运行的工作流被取消。 调用的工作流在${{ github.workflow }}中使用其调用方工作流的名称，因此将此上下文用作调用和被调用工作流中的`jobs.<job_id>.concurrency.group`值时，会导致在被调用工作流运行时调用方工作流被取消。\n\n### 可重用工作流程如何使用运行器\n\n#### GitHub-托管运行者\n\n始终仅使用调用者的上下文来评估 GitHub-hosted runners 的分配。\nGitHub托管运行器的计费总是与调用者相关联。 调用方工作流不能使用来自被调用存储库的GitHub托管运行器。 有关详细信息，请参阅“[GitHub 托管的运行程序](/zh/enterprise-cloud@latest/actions/using-github-hosted-runners/about-github-hosted-runners)”。\n\n#### 自托管运行程序\n\n与调用方工作流相同的用户或组织 或企业 拥有的调用工作流可以从调用方上下文中访问自承载运行程序。 这意味着被调用的工作流程可以访问自托管运行器，这些运行器具有以下特点：\n\n* 在调用方存储库中\n* 在调用方存储库的组织或企业中，前提是该运行器已经提供给调用方存储库\n\n### 嵌套工作流程的访问权限和权限\n\n如果初始调用方工作流无法访问任何嵌套工作流，则包含嵌套可重用工作流的工作流会失败。 有关详细信息，请参阅[可重用工作流程的访问权限](#access-to-reusable-workflows)。\n\n`GITHUB_TOKEN` 权限在嵌套工作流中只能相同或更严格。 例如，在工作流链 A > B > C 中，如果工作流 A 具有 `package: read` 令牌权限，则 B 和 C 不能具有 `package: write` 权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/enterprise-cloud@latest/actions/security-guides/automatic-token-authentication)”。\n\n有关如何使用 API 确定特定工作流运行中涉及哪些工作流文件的信息，请参阅 [重用工作流](/zh/enterprise-cloud@latest/actions/how-tos/sharing-automations/reuse-workflows#monitoring-which-workflows-are-being-used)。\n\n### 重新运行作业时可重用工作流程的行为\n\n可使用 SHA、发布标记或分支名称引用公共存储库中的可重用工作流。 有关详细信息，请参阅“[重用工作流](/zh/enterprise-cloud@latest/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow)”。\n\n重新运行使用可重用工作流且引用不是 SHA 的工作流时，有一些行为需要注意：\n\n* 重新运行工作流中的所有作业时将使用指定引用中的可重用工作流。 有关重新运行工作流中所有作业的详细信息，请参阅 [重新运行工作流程和作业](/zh/enterprise-cloud@latest/actions/managing-workflow-runs/re-running-workflows-and-jobs#re-running-all-the-jobs-in-a-workflow)。\n* 重新运行失败的作业或工作流中的特定作业时将使用第一次尝试的同一提交 SHA 中的可重用工作流。 有关重新运行工作流中失败作业的详细信息，请参阅 [重新运行工作流程和作业](/zh/enterprise-cloud@latest/actions/managing-workflow-runs/re-running-workflows-and-jobs#re-running-failed-jobs-in-a-workflow)。 有关重新运行工作流中特定作业的详细信息，请参阅 [重新运行工作流程和作业](/zh/enterprise-cloud@latest/actions/managing-workflow-runs/re-running-workflows-and-jobs#re-running-a-specific-job-in-a-workflow)。\n\n### `github` 背景信息\n\n当可重用工作流由调用方工作流触发时，`github` 上下文始终与调用方工作流关联。 调用的工作流会自动授予对 `github.token` 和 `secrets.GITHUB_TOKEN` 访问权限。 有关 `github` 上下文的详细信息，请参阅“[上下文参考](/zh/enterprise-cloud@latest/actions/learn-github-actions/contexts#github-context)”。\n\n## 工作流模板\n\n为组织创建工作流模板时要使用的参考信息。\n\n### 工作流模板可用性\n\n可以在匹配的存储库或受限可见性高于模板存储库的存储库中使用模板。\n\n* 公共 `.github` 存储库中的工作流模板可用于所有存储库类型。\n* 内部 `.github` 存储库中的工作流模板仅适用于内部和专用存储库。\n* 专用 `.github` 存储库中的工作流模板仅适用于专用存储库。\n\n由于公共工作流模板需要公共 `.github` 存储库，因此它们不可用 Enterprise Managed Users。\n\n### 授予专用/内部存储库的访问权限\n\n如果使用专用或内部 `.github` 存储库，则需要向应该能够使用模板的用户或团队授予读取访问权限。\n\n### `$default-branch` 占位符\n\n如果需要引用存储库的默认分支，可以在工作流模板中使用 `$default-branch` 占位符。 创建工作流程时，占位符将自动替换为仓库默认分支的名称。\n\n### 示例工作流模板文件\n\n此文件名为 `octo-organization-ci.yml`，用于演示基本工作流。\n\n```yaml copy\nname: Octo Organization CI\non:\n  push:\n    branches: [ $default-branch ]\n  pull_request:\n    branches: [ $default-branch ]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Run a one-line script\n        run: echo Hello from Octo Organization\n```\n\n### 元数据文件要求\n\n元数据文件必须与工作流程文件同名，但扩展名不是 `.yml`，而必须附加 `.properties.json`。 例如，名为 `octo-organization-ci.properties.json` 的文件包含名为 `octo-organization-ci.yml` 的工作流文件的元数据：\n\n```json copy\n{\n    \"name\": \"Octo Organization Workflow\",\n    \"description\": \"Octo Organization CI workflow template.\",\n    \"iconName\": \"example-icon\",\n    \"categories\": [\n        \"Go\"\n    ],\n    \"filePatterns\": [\n        \"package.json$\",\n        \"^Dockerfile\",\n        \".*\\\\.md$\"\n    ]\n}\n```\n\n* `name`\n\n- **必需。** 工作流的名称。 这会显示在可用工作流程列表中。\n\n* `description`\n\n- **必需。** 工作流的说明。 这会显示在可用工作流程列表中。\n\n* `iconName`\n\n- **可选。** 指定工作流列表中显示的工作流图标。\n  `iconName` 可以是以下类型之一：\n  * 存储在 `workflow-templates` 目录中的 SVG 文件。 若要引用文件，该值必须是不带文件扩展名的文件名。 例如，名为 `example-icon.svg` 的 SVG 文件被引用为 `example-icon`。\n  * 来自 GitHub 的 [Octicons](https://primer.style/octicons/) 集的图标。 若要引用 octicon，该值必须为 `octicon <icon name>`。 例如，`octicon smiley`。\n\n* `categories`\n\n- **可选。** 定义用于显示工作流的类别。 可以使用以下列表中的类别名称：\n  * [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) 存储库中的一般类别名称。\n  * [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) 存储库列表中的 linguist 语言。\n  * [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) 存储库的列表中支持的技术堆栈。\n\n* `filePatterns`\n\n- **可选。** 如果用户的存储库在其根目录中具有与定义的正则表达式匹配的文件，则允许使用工作流。\n\n## YAML 定位点和别名\n\n可以使用 YAML 定位点和别名来减少工作流中的重复。 定位点（标记为 `&`）标识要重用的内容，而别名（标记为 `*`）在另一个位置重复该内容。\n\n有关定位点和别名的详细信息，请参阅 [YAML 规范中的节点定位点和别名](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases)。\n\n下面是将 YAML 定位点和别名与环境变量配合使用的示例：\n\n```yaml\njobs:\n  job1:\n    env: &env_vars # Define the anchor on first use\n      NODE_ENV: production\n      DATABASE_URL: ${{ secrets.DATABASE_URL }}\n    steps:\n      - run: echo \"Using production settings\"\n\n  job2:\n    env: *env_vars # Reuse the environment variables\n    steps:\n      - run: echo \"Same environment variables here\"\n```\n\n这相当于在没有定位点和别名的情况下编写以下 YAML：\n\n```yaml\njobs:\n  job1:\n    env:\n      NODE_ENV: production\n      DATABASE_URL: ${{ secrets.DATABASE_URL }}\n    steps:\n      - run: echo \"Using production settings\"\n\n  job2:\n    env:\n      NODE_ENV: production\n      DATABASE_URL: ${{ secrets.DATABASE_URL }}\n    steps:\n      - run: echo \"Same environment variables here\"\n```\n\n还可以将定位点用于更复杂的配置，例如重用整个作业配置：\n\n```yaml\njobs:\n  test: &base_job # Define the anchor on first use\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    env:\n      NODE_VERSION: '18'\n    steps:\n      - uses: actions/checkout@v6\n      - name: Set up Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ env.NODE_VERSION }}\n      - run: npm test\n\n  alt-test: *base_job # Reuse the entire job configuration\n```"}