# 重用工作流配置

通过重用现有工作流和使用 YAML 定位点和别名时避免重复的信息。

## 可重用工作流

本文提供有关可重用工作流和工作流模板的参考信息，包括访问规则、限制、支持的关键字和运行程序行为。

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

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

* 这两个工作流程位于同一存储库中。

* 调用的工作流存储在公共存储库GitHub Enterprise Server中。

  不能直接使用在GitHub.com中定义的可重用工作流。 而是将可重用工作流的副本存储在该路径上 你的 GitHub Enterprise Server 实例，并从该路径调用工作流。

* 被调用的工作流程存储在内部存储库中，该存储库的设置允许对其进行访问。 有关详细信息，请参阅 [与企业共享操作和工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/share-with-your-enterprise)。

* 被调用的工作流存储在专用存储库中，该存储库的设置允许对其进行访问。 有关详细信息，请参阅 [与企业共享操作和工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/share-with-your-enterprise)。

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

| 调用方存储库                | 可访问的工作流存储库 |
| --------------------- | ---------- |
| `private`             |            |
| `private`             |            |
| 、`internal`和`public`  |            |
|                       |            |
| `internal`            |            |
| `internal` 和 `public` |            |
|                       |            |
| `public`              | `public`   |

调用方存储库的“操作设置”页面上的**操作权限**必须配置为允许使用操作和可重用工作流 - 请参阅 [管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/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)。

对于 内部存储库或 专用存储库，必须显式配置调用工作流存储库的“操作设置”页上 **的访问策略，** 以允许从包含调用方工作流的存储库进行访问 - 请参阅 [管理存储库的GitHub Actions设置](/zh/enterprise-server@3.22/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)。

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

### 可重用工作流的限制

* 最多可以连接到四个级别的工作流。 有关详细信息，请参阅“[嵌套可重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#nesting-reusable-workflows)”。

* 可以从单个工作流文件调用最多 20 个唯一可重用工作流。 此限制包括可能从顶层调用方工作流文件开始调用的任何嵌套可重用工作流树。

  例如，*top-level-caller-workflow\.yml* → *called-workflow-1.yml* → *called-workflow-2.yml* 计为 2 个可重用工作流。

* 对于在调用方工作流中的工作流级别定义的 `env` 上下文，在其中设置的任何环境变量都不会传播到被调用的工作流。 有关详细信息，请参阅 [在变量中存储信息](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables) 和 [上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#env-context)。

* 同样，对于在被调用的工作流中定义的 `env` 上下文，无法在调用方工作流的 `env` 上下文中访问在其中设置的环境变量。 必须改用可重用工作流的输出。 有关详细信息，请参阅“[使用可重用工作流的输出](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#using-outputs-from-a-reusable-workflow)”。

* 若要在多个工作流中重复使用变量，请在组织、存储库或环境级别设置变量，并使用 `vars` 上下文来引用它们。 有关详细信息，请参阅 [在变量中存储信息](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables) 和 [上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#vars-context)。

* 可重用工作流直接在作业中调用，而不是从作业步骤中调用。 因此，不能使用 `GITHUB_ENV` 将值传递给调用方工作流中的作业步骤。

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

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

* [`jobs.<job_id>.name`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname)
* [`jobs.<job_id>.uses`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iduses)
* [`jobs.<job_id>.with`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idwith)
* [`jobs.<job_id>.with.<input_id>`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idwithinput_id)
* [`jobs.<job_id>.secrets`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecrets)
* [`jobs.<job_id>.secrets.<secret_id>`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretssecret_id)
* [`jobs.<job_id>.secrets.inherit`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretsinherit)
* [`jobs.<job_id>.strategy`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategy)
* [`jobs.<job_id>.needs`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idneeds)
* [`jobs.<job_id>.if`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idif)
* [`jobs.<job_id>.concurrency`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency)
* [`jobs.<job_id>.permissions`](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions)

  > \[!NOTE]
  >
  > * 如果调用作业中未指定 `jobs.<job_id>.permissions`，则调用的工作流将具有 `GITHUB_TOKEN` 的默认权限。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#permissions)”。
  > * 从调用方工作流传递的 `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 托管的运行程序](/zh/enterprise-server@3.22/actions/concepts/runners/github-hosted-runners)”。

#### 自托管运行程序

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

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

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

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

`GITHUB_TOKEN` 权限在嵌套工作流中只能相同或更严格。 例如，在工作流链 A > B > C 中，如果工作流 A 具有 `package: read` 令牌权限，则 B 和 C 不能具有 `package: write` 权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token)”。

有关如何使用 API 确定特定工作流运行中涉及哪些工作流文件的信息，请参阅 [重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#monitoring-which-workflows-are-being-used)。

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

可使用 SHA、发布标记或分支名称引用公共存储库中的可重用工作流。 有关详细信息，请参阅“[重用工作流](/zh/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#calling-a-reusable-workflow)”。

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

* 重新运行工作流中的所有作业时将使用指定引用中的可重用工作流。 有关重新运行工作流中所有作业的详细信息，请参阅 [重新运行工作流程和作业](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-all-the-jobs-in-a-workflow)。
* 重新运行失败的作业或工作流中的特定作业时，将使用来自首次尝试所用同一提交 SHA 的可重用工作流。 有关重新运行工作流中失败作业的详细信息，请参阅 [重新运行工作流程和作业](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-failed-jobs-in-a-workflow)。 有关重新运行工作流中特定作业的详细信息，请参阅 [重新运行工作流程和作业](/zh/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-a-specific-job-in-a-workflow)。

### `github` 背景信息

当可重用工作流由调用方工作流触发时，`github` 上下文始终与调用方工作流关联。 调用的工作流会自动授予对 `github.token` 和 `secrets.GITHUB_TOKEN` 访问权限。 有关 `github` 上下文的详细信息，请参阅“[上下文参考](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context)”。

## 工作流模板

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

### `$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 copy
name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - 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 copy
{
    "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](https://primer.style/octicons/) 集的图标。 若要引用 octicon，该值必须为 `octicon <icon name>`。 例如，`octicon smiley`。

* `categories`

- **可选。** 定义用于显示工作流的类别。 可以使用以下列表中的类别名称：
  * [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) 存储库中的一般类别名称。
  * [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) 存储库列表中的 linguist 语言。
  * [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) 存储库的列表中支持的技术堆栈。

* `filePatterns`

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