# 触发工作流的事件

可以配置工作流，使其在GitHub上发生特定活动时、在计划的时间运行，或在GitHub之外发生事件时启动。

## 关于触发工作流的事件

工作流触发器是导致工作流运行的事件。 有关如何使用工作流触发器的详细信息，请参阅 [触发工作流程](/zh/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow)。

某些事件具有多种活动类型。 对于这些事件，你可以指定将触发工作流运行的活动类型。 有关每个活动类型的含义的详细信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads)。

> \[!NOTE]
> 并非所有 Webhook 事件都会触发工作流。

## `branch_protection_rule`

| Web 挂钩事件有效负载                                                                                | 活动类型                                       | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------ | ------------ |
| [`branch_protection_rule`](/zh/webhooks/webhook-events-and-payloads#branch_protection_rule) | - `created`<br/>- `edited`<br/>- `deleted` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#branch_protection_rule)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在工作流存储库中的分支保护规则发生更改时运行工作流。 有关分支保护规则的详细信息，请参阅“[关于受保护分支](/zh/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)”。 有关分支保护规则 API 的信息，请参阅 GraphQL API 文档中的 [Branches](/zh/graphql/reference/branches#object-branchprotectionrule) 或 [分支的 REST API 终结点及其设置](/zh/rest/branches)。

例如，可以在分支保护规则状态为 `created` 或 `deleted` 时运行工作流：

```yaml
on:
  branch_protection_rule:
    types: [created, deleted]
```

## `check_run`

| Web 挂钩事件有效负载                                                      | 活动类型                                                                       | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------ | ------------ |
| [`check_run`](/zh/webhooks/webhook-events-and-payloads#check_run) | - `created`<br/>- `rerequested`<br/>- `completed`<br/>- `requested_action` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#check_run)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * 为了防止递归工作流，如果检查运行的检查套件是由 GitHub Actions 创建的，或者检查套件的头 SHA 与 GitHub Actions 相关联，则此事件不会触发工作流。

在发生与检查运行相关的活动时运行工作流。 检查运行是检查套件中的单个测试。 如需相关信息，请参阅 [使用 REST API 与检查交互](/zh/rest/guides/using-the-rest-api-to-interact-with-checks)。 有关检查运行 API 的信息，请参阅 GraphQL API 文档中的 [检查](/zh/graphql/reference/checks#object-checkrun)或 [检查运行的 REST API 终结点](/zh/rest/checks/runs)。

例如，可以在检查运行状态为 `rerequested` 或 `completed` 时运行工作流。

```yaml
on:
  check_run:
    types: [rerequested, completed]
```

## `check_suite`

| Web 挂钩事件有效负载                                                          | 活动类型          | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------------------------------------------------------- | ------------- | ------------ | ------------ |
| [`check_suite`](/zh/webhooks/webhook-events-and-payloads#check_suite) | - `completed` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#check_suite)。 尽管仅支持 `completed` 活动类型，但如果将来添加更多活动类型，则指定活动类型将确保工作流保持特定。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * 为了防止递归工作流，如果检查套件是由 GitHub Actions 创建的，或者检查套件的头 SHA 与 GitHub Actions 关联，则此事件不会触发工作流。

在发生检查套件活动时运行工作流。 检查套件是为特定提交创建的检查运行的集合。 检查套件汇总了套件中检查运行的状态和结论。 如需相关信息，请参阅 [使用 REST API 与检查交互](/zh/rest/guides/using-the-rest-api-to-interact-with-checks)。 有关检查套件 API 的信息，请参阅 GraphQL API 文档中的 [检查](/zh/graphql/reference/checks#object-checksuite) 或 [REST API 端点用于检查套件](/zh/rest/checks/suites)。

例如，可以在检查运行状态为 `completed` 时运行工作流。

```yaml
on:
  check_suite:
    types: [completed]
```

## `create`

| Web 挂钩事件有效负载                                                | 活动类型 | `GITHUB_SHA`   | `GITHUB_REF` |
| ----------------------------------------------------------- | ---- | -------------- | ------------ |
| [`create`](/zh/webhooks/webhook-events-and-payloads#create) | 不适用  | 创建的分支或标记上的最新提交 | 创建的分支或标记     |

> \[!NOTE]
> 一次创建三个以上的标记时，不会创建事件。

当有人在工作流的存储库中创建 Git 引用（Git 分支或标记）时运行工作流。 有关用于创建 Git 引用的 API 的信息，请参阅 GraphQL API 文档中的 [Git](/zh/graphql/reference/git#mutation-createref) 或 [Git 参考的 REST API 端点](/zh/rest/git/refs#create-a-reference)。

例如，可以在发生 `create` 事件时运行工作流。

```yaml
on:
  create
```

## `delete`

| Web 挂钩事件有效负载                                                | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------- | ---- | ------------ | ------------ |
| [`delete`](/zh/webhooks/webhook-events-and-payloads#delete) | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * 一次删除三个以上的标记时，不会创建事件。

当有人删除工作流存储库中的 Git 引用（Git 分支或标记）时运行工作流。 有关用于删除 Git 引用的 API 的信息，请参阅 GraphQL API 文档中的 [Git](/zh/graphql/reference/git#mutation-deleteref) 或 [Git 参考的 REST API 端点](/zh/rest/git/refs#delete-a-reference)。

例如，可以在发生 `delete` 事件时运行工作流。

```yaml
on:
  delete
```

## `deployment`

| Web 挂钩事件有效负载                                                        | 活动类型 | `GITHUB_SHA` | `GITHUB_REF`                 |
| ------------------------------------------------------------------- | ---- | ------------ | ---------------------------- |
| [`deployment`](/zh/webhooks/webhook-events-and-payloads#deployment) | 不适用  | 要部署的提交       | 要部署的分支或标记（如果使用提交 SHA 创建，则为空） |

当有人在工作流的存储库中创建部署时运行工作流。 使用提交 SHA 创建的部署可能没有 Git 引用。有关用于创建部署的 API 的信息，请参阅 GraphQL API 文档中的 [Deployments](/zh/graphql/reference/deployments#mutation-createdeployment) 或 [存储库的 REST API 终结点](/zh/rest/repos#deployments)。

例如，可以在发生 `deployment` 事件时运行工作流。

```yaml
on:
  deployment
```

## `deployment_status`

| Web 挂钩事件有效负载                                                                      | 活动类型 | `GITHUB_SHA` | `GITHUB_REF`     |
| --------------------------------------------------------------------------------- | ---- | ------------ | ---------------- |
| [`deployment_status`](/zh/webhooks/webhook-events-and-payloads#deployment_status) | 不适用  | 要部署的提交       | 要部署的分支或标记（提交时为空） |

> \[!NOTE]
> 将部署状态设置为 `inactive` 时，不会触发工作流运行。

在第三方提供部署状态时运行工作流。 使用提交 SHA 创建的部署可能没有 Git 引用。有关用于创建部署状态的 API 的信息，请参阅 GraphQL API 文档中的 [Deployments](/zh/graphql/reference/deployments#mutation-createdeploymentstatus) 或 [适用于部署的 REST API 终结点](/zh/rest/deployments#create-a-deployment-status)。

例如，可以在发生 `deployment_status` 事件时运行工作流。

```yaml
on:
  deployment_status
```

## `discussion`

| Web 挂钩事件有效负载                                                        | 活动类型                                                                                                                                                                                                                            | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------ |
| [`discussion`](/zh/webhooks/webhook-events-and-payloads#discussion) | - `created`<br/>- `edited`<br/>- `deleted`<br/>- `transferred`<br/>- `pinned`<br/>- `unpinned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `locked`<br/>- `unlocked`<br/>- `category_changed`<br/> - `answered`<br/> - `unanswered` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#discussion)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * GitHub Discussions 的 Webhook 事件目前为 公开预览，可能会有变动。

在创建或修改工作流存储库中的讨论时运行工作流。 对于与讨论评论相关的活动，请使用 [`discussion_comment`](#discussion_comment) 事件。 有关讨论的详细信息，请参阅 [关于讨论](/zh/discussions/collaborating-with-your-community-using-discussions/about-discussions)。 有关 GraphQL API 的信息，请参阅 [讨论](/zh/graphql/reference/discussions#object-discussion)。

例如，可以在讨论状态为 `created`、`edited` 或 `answered` 时运行工作流。

```yaml
on:
  discussion:
    types: [created, edited, answered]
```

## `discussion_comment`

| Web 挂钩事件有效负载                                                                        | 活动类型                                            | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------------------------- | ----------------------------------------------- | ------------ | ------------ |
| [`discussion_comment`](/zh/webhooks/webhook-events-and-payloads#discussion_comment) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#discussion_comment)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * GitHub Discussions 的 Webhook 事件目前为 公开预览，可能会有变动。

在创建或修改工作流存储库中讨论的评论时运行工作流。 对于与讨论（而非讨论的评论）相关的活动，请使用 [`discussion`](#discussion) 事件。 有关讨论的详细信息，请参阅 [关于讨论](/zh/discussions/collaborating-with-your-community-using-discussions/about-discussions)。 有关 GraphQL API 的信息，请参阅 [讨论](/zh/graphql/reference/discussions#object-discussion)。

例如，可以在讨论评论的状态为 `created` 或 `deleted` 时运行工作流。

```yaml
on:
  discussion_comment:
    types: [created, deleted]
```

## `fork`

| Web 挂钩事件有效负载                                            | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------- | ---- | ------------ | ------------ |
| [`fork`](/zh/webhooks/webhook-events-and-payloads#fork) | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

当有人复刻存储库时运行工作流。 有关 REST API 的信息，请参阅 [分支的 REST API 终结点](/zh/rest/repos/forks#create-a-fork)。

例如，可以在发生 `fork` 事件时运行工作流。

```yaml
on:
  fork
```

## `gollum`

| Web 挂钩事件有效负载                                                | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------- | ---- | ------------ | ------------ |
| [`gollum`](/zh/webhooks/webhook-events-and-payloads#gollum) | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在有人创建或更新 Wiki 页面时运行工作流。 有关详细信息，请参阅“[关于 Wiki 页面](/zh/communities/documenting-your-project-with-wikis/about-wikis)”。

例如，可以在发生 `gollum` 事件时运行工作流。

```yaml
on:
  gollum
```

## `image_version`

| Web 挂钩事件有效负载 | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ------------ | ---- | ------------ | ------------ |
| 不适用          | 不适用  | 默认分支上的最新提交   | 默认分支         |

当指定映像的新版本可供使用时，运行工作流。 此事件通常在成功创建映像版本后触发，你可以自动执行部署或通知等操作，以回应新的映像版本。

此事件支持 glob 模式的映像名称和版本。 以下示例在新的映像版本与任何指定名称和版本组合匹配时触发。 例如：`["MyNewImage", 1.0.0]`、`["MyNewImage", 2.53.0]`、`["MyOtherImage", 1.0.0]` 和 `["MyOtherImage", 2.0.0]`。

```yaml
on:
  image_version:
    names:
    - "MyNewImage"
    - "MyOtherImage"
    versions:
    - 1.*
    - 2.*
```

## `issue_comment`

| Web 挂钩事件有效负载                                                              | 活动类型                                            | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------------------------- | ----------------------------------------------- | ------------ | ------------ |
| [`issue_comment`](/zh/webhooks/webhook-events-and-payloads#issue_comment) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#issue_comment)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在创建、编辑或删除议题或拉取请求评论时运行工作流。 有关问题注释 API 的信息，请参阅 GraphQL API 文档中的 [问题](/zh/graphql/reference/issues#object-issuecomment) 或 REST API 文档中的 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#issue_comment)。

例如，可以在问题或拉取请求评论的状态为 `created` 或 `deleted` 时运行工作流。

```yaml
on:
  issue_comment:
    types: [created, deleted]
```

### 仅问题或仅拉取请求的 `issue_comment`

对于问题和拉取请求的注释，都会发生 `issue_comment` 事件。 可以在条件中使用 `github.event.issue.pull_request` 属性，根据触发对象是问题还是拉取请求来执行不同的操作。

例如，仅当 `pr_commented` 事件源自拉取请求时，此工作流才会运行 `issue_comment` 作业。 仅当 `issue_commented` 事件源自问题时，才会运行 `issue_comment` 作业。

```yaml
on: issue_comment

jobs:
  pr_commented:
    # This job only runs for pull request comments
    name: PR comment
    if: ${{ github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo A comment on PR $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}

  issue_commented:
    # This job only runs for issue comments
    name: Issue comment
    if: ${{ !github.event.issue.pull_request }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo A comment on issue $NUMBER
        env:
          NUMBER: ${{ github.event.issue.number }}
```

## `issues`

| Web 挂钩事件有效负载                                                | 活动类型                                                                                                                                                                                                                                                                                                                                                     | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------ |
| [`issues`](/zh/webhooks/webhook-events-and-payloads#issues) | - `opened`<br/>- `edited`<br/>- `deleted`<br/>- `transferred`<br/>- `pinned`<br/>- `unpinned`<br/>- `closed`<br/>- `reopened`<br/>- `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `locked`<br/>- `unlocked`<br/>- `milestoned`<br/> - `demilestoned`<br/> - `typed`<br/> - `untyped`<br/> - `field_added`<br/> - `field_removed` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#issues)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在创建或修改工作流存储库中的议题时运行工作流。 对于与问题中的注释相关的活动，请使用 [`issue_comment`](#issue_comment) 事件。 有关问题的详细信息，请参阅 [关于问题](/zh/issues/tracking-your-work-with-issues/learning-about-issues/about-issues)。 有关问题 API 的信息，请参阅 GraphQL API 文档中的 [问题](/zh/graphql/reference/issues#object-issue) 或 [适用于问题的 REST API 终结点](/zh/rest/issues)。

例如，可以在问题状态为 `opened`、`edited` 或 `milestoned` 时运行工作流。

```yaml
on:
  issues:
    types: [opened, edited, milestoned]
```

还可以在设置、更改或清除问题字段值时运行工作流。
`field_added` 活动类型会在首次设置字段值和更新现有值时都触发。 当字段值被清除时，`field_removed` 活动类型会触发。

```yaml
on:
  issues:
    types: [field_added, field_removed]
```

## `label`

| Web 挂钩事件有效负载                                              | 活动类型                                            | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------------------------------------------- | ----------------------------------------------- | ------------ | ------------ |
| [`label`](/zh/webhooks/webhook-events-and-payloads#label) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#label)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在创建或修改工作流存储库中的标签时运行工作流。 有关标签的详细信息，请参阅 [管理标签](/zh/issues/using-labels-and-milestones-to-track-work/managing-labels)。 有关标签 API 的信息，请参阅 GraphQL API 文档中的 [问题](/zh/graphql/reference/issues#object-label) 或 [适用于标签的 REST API 终结点](/zh/rest/issues/labels)。

如果要在问题、拉取请求或讨论中添加或删除标签时运行工作流，请针对 `labeled`、`unlabeled`、`issues` 或 [](#issues) 事件改用 `pull_request` 或 [](#pull_request) 活动类型。

例如，可以在标签状态为 `created` 或 `deleted` 时运行工作流。

```yaml
on:
  label:
    types: [created, deleted]
```

## `merge_group`

| Web 挂钩事件有效负载                                                          | 活动类型               | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------------------------------------------------------- | ------------------ | ------------ | ------------ |
| [`merge_group`](/zh/webhooks/webhook-events-and-payloads#merge_group) | `checks_requested` | 合并组的 SHA     | 合并组的引用       |

> \[!NOTE]
>
> *

多个活动类型会触发此事件。 尽管仅 `checks_requested` 支持活动类型，但如果将来添加更多活动类型，则指定活动类型将保留工作流的特定状态。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#merge_group)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。

> * 如果存储库使用 GitHub Actions 执行所需检查 要求工作流，则需要更新工作流以包含 `merge_group` 事件作为其他触发器。 否则在将拉取请求添加到合并队列时不会触发状态检查。 合并将失败，因为没有报告必要的状态检查。 事件 `merge_group` 独立于 `pull_request` 和 `push` 事件。

将拉取请求添加到合并队列时运行工作流，将拉取请求添加到合并组。 有关详细信息，请参阅“[将拉取请求与合并队列合并](/zh/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue)”。

例如，可以在发生 `checks_requested` 活动时运行工作流。

```yaml
on:
  pull_request:
    branches: [ "main" ]
  merge_group:
    types: [checks_requested]
```

## `milestone`

| Web 挂钩事件有效负载                                                      | 活动类型                                                                          | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------ | ------------ |
| [`milestone`](/zh/webhooks/webhook-events-and-payloads#milestone) | - `created`<br/>- `closed`<br/>- `opened`<br/>- `edited`<br/>- `deleted`<br/> | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#milestone)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在创建或修改工作流存储库中的里程碑时运行工作流。 有关里程碑的详细信息，请参阅 [关于里程碑](/zh/issues/using-labels-and-milestones-to-track-work/about-milestones)。 有关里程碑 API 的信息，请参阅 GraphQL API 文档中的 [问题](/zh/graphql/reference/issues#object-milestone) 或 [适用于里程碑的 REST API 终结点](/zh/rest/issues/milestones)。

若想要在将问题添加到里程碑或从里程碑中删除问题时运行工作流，请针对 `milestoned` 事件改用 `demilestoned` 或 `issues` 活动类型。

例如，可以在里程碑状态为 `opened` 或 `deleted` 时运行工作流。

```yaml
on:
  milestone:
    types: [opened, deleted]
```

## `page_build`

| Web 挂钩事件有效负载                                                        | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------------------- | ---- | ------------ | ------------ |
| [`page_build`](/zh/webhooks/webhook-events-and-payloads#page_build) | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

如果在存储库中启用 GitHub Pages，则在有人推送到作为 GitHub Pages 发布源的分支时运行工作流。 有关发布源的详细信息 GitHub Pages ，请参阅 [为您的 GitHub Pages 网站配置发布源](/zh/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)。 有关 REST API 的信息，请参阅 [存储库的 REST API 终结点](/zh/rest/repos#pages)。

例如，可以在发生 `page_build` 事件时运行工作流。

```yaml
on:
  page_build
```

## `public`

| Web 挂钩事件有效负载                                                | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------- | ---- | ------------ | ------------ |
| [`public`](/zh/webhooks/webhook-events-and-payloads#public) | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

当工作流的存储库从私有变为公共时运行工作流。 有关 REST API 的信息，请参阅 [存储库的 REST API 终结点](/zh/rest/repos#edit)。

例如，可以在发生 `public` 事件时运行工作流。

```yaml
on:
  public
```

## `pull_request`

| Web 挂钩事件有效负载                                                            | 活动类型                                                                                                                                                                                                                                                                                                                                                                                                                             | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------ |
| [`pull_request`](/zh/webhooks/webhook-events-and-payloads#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `converted_to_draft`<br/>- `locked`<br/>- `unlocked`<br/>- `enqueued`<br/>- `dequeued`<br/>- `milestoned`<br/>- `demilestoned`<br/>- `ready_for_review`<br/>- `review_requested`<br/>- `review_request_removed`<br/>- `auto_merge_enabled`<br/>- `auto_merge_disabled` |              |              |
| `GITHUB_REF` 分支上的最后一次合并提交                                               | PR 合并分支 `refs/pull/PULL_REQUEST_NUMBER/merge`                                                                                                                                                                                                                                                                                                                                                                                    |              |              |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#pull_request)。 默认情况下，工作流仅在 `pull_request` 事件的活动类型为 `opened`、`synchronize` 或 `reopened` 时运行。 要按不同的活动类型触发工作流，请使用 `types` 关键字。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 如果拉取请求存在合并冲突，工作流将不会在 `pull_request` 活动上运行。 必须先解决合并冲突。 相反，具有 `pull_request_target` 事件的工作流将运行，即使拉取请求存在合并冲突也是如此。 在使用 `pull_request_target` 触发器之前，应注意安全风险。 有关详细信息，请参阅 [`pull_request_target`](#pull_request_target)。
> * 对于已合并的拉取请求以及来自分叉存储库的拉取请求，`pull_request`webhook 事件负载为空。
> * 当工作流使用 `GITHUB_TOKEN` 创建或更新拉取请求时，具有 `pull_request`、`opened` 或 `synchronize` 活动类型的 `reopened` 事件会创建需要审批的工作流运行。 具有存储库写入权限的用户可以从拉取请求页面批准这些运行。 除了 `workflow_dispatch` 和 `repository_dispatch` 之外，其他由 `GITHUB_TOKEN` 触发的事件完全不会创建工作流运行。
> * 已关闭的拉取请求的 `GITHUB_REF` 值会根据该拉取请求是否已被合并而有所不同。 如果拉取请求已关闭但未合并，则值为 `refs/pull/PULL_REQUEST_NUMBER/merge`。 如果拉取请求因被合并而关闭，则它将是合并到的分支的完全限定 `ref`，例如 `/refs/heads/main`。

在工作流存储库中发生有关拉取请求的活动时运行工作流。 例如，如果未指定任何活动类型，则工作流将在打开或重新打开拉取请求时运行，或者在更新拉取请求的头部分支时运行。 对于与拉取请求审查、拉取请求审查评论或拉取请求评论相关的活动，请改用 [`pull_request_review`](#pull_request_review)、[`pull_request_review_comment`](#pull_request_review_comment) 或 [`issue_comment`](#issue_comment) 事件。 有关拉取请求 API 的信息，请参阅 GraphQL API 文档中的 [拉取请求](/zh/graphql/reference/pulls#object-pullrequest) 或 [用于拉取请求的 REST API 终结点](/zh/rest/pulls)。

请注意，此事件的 `GITHUB_SHA` 是拉取请求合并分支的最后一个合并提交。 如果要获取最后一次提交到拉取请求的头部分支的提交 ID，请改用 `github.event.pull_request.head.sha`。 有关合并分支的详细信息，请参阅 [拉取请求](/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#pull-request-refs-and-merge-branches)。

### 合并分支如何影响工作流

对于打开的可合并拉取请求，`pull_request` 事件触发的工作流会将 `GITHUB_REF` 设置为合并分支。 由于 `actions/checkout` 默认使用 `GITHUB_REF` ，因此会检查出合并分支。 CI 测试是针对合并后的结果运行，而不仅限于主分支。

* ```
            将 `GITHUB_REF` 设置为 `refs/pull/PULL_REQUEST_NUMBER/merge`
  ```
* `GITHUB_SHA` 是合并分支上的合并提交的 SHA

若要仅测试头部分支提交而不模拟合并，请在工作流中使用 `github.event.pull_request.head.sha` 签出头部分支。

例如，你可以在打开或重新打开拉取请求时运行工作流。

```yaml
on:
  pull_request:
    types: [opened, reopened]
```

你可以使用事件上下文进一步控制工作流中作业的运行时间。 例如，当请求对拉取请求进行审查时，将运行此工作流，但 `specific_review_requested` 作业仅在请求 `octo-team` 审查时运行。

```yaml
on:
  pull_request:
    types: [review_requested]
jobs:
  specific_review_requested:
    runs-on: ubuntu-latest
    if: ${{ github.event.requested_team.name == 'octo-team'}}
    steps:
      - run: echo 'A review from octo-team was requested'
```

### 基于拉取请求的主要分支或基础分支运行 `pull_request` 工作流

可以使用 `branches` 或 `branches-ignore` 筛选器配置工作流，使其仅在面向特定分支的拉取请求上运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore)”。

例如，当有人打开面向名称以 `releases/` 开头的分支的拉取请求时，此工作流将运行：

```yaml
on:
  pull_request:
    types:
      - opened
    branches:
      - 'releases/**'
```

> \[!NOTE]
> 如果同时使用 `branches` 筛选器和 `paths` 筛选器，则工作流将只在这两个筛选器都满足条件时运行。 例如，仅当在名称以 `.js` 开头的分支上打开包含 JavaScript (`releases/`) 文件更改的拉取请求时，才会运行以下工作流：
>
> ```yaml
> on:
>   pull_request:
>     types:
>       - opened
>     branches:
>       - 'releases/**'
>     paths:
>       - '**.js'
> ```

要基于拉取请求的头部分支名称（而不是拉取请求的基本分支名称）运行作业，请在条件中使用 `github.head_ref` 上下文。 例如，每当打开拉取请求时，此工作流都会运行，但仅当拉取请求的头部是名称以 `run_if` 开头的分支时，才会执行 `releases/` 作业：

```yaml
on:
  pull_request:
    types:
      - opened
jobs:
  run_if:
    if: startsWith(github.head_ref, 'releases/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "The head of this PR starts with 'releases/'"
```

### 基于拉取请求中更改的文件运行 `pull_request` 工作流

你还可以将工作流配置为在拉取请求更改特定文件时运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)”。

例如，当拉取请求包含对 JavaScript 文件 (`.js`) 的更改时，此工作流将运行：

```yaml
on:
  pull_request:
    paths:
      - '**.js'
```

> \[!NOTE]
> 如果同时使用 `branches` 筛选器和 `paths` 筛选器，则工作流将只在这两个筛选器都满足条件时运行。 例如，仅当在名称以 `.js` 开头的分支上打开包含 JavaScript (`releases/`) 文件更改的拉取请求时，才会运行以下工作流：
>
> ```yaml
> on:
>   pull_request:
>     types:
>       - opened
>     branches:
>       - 'releases/**'
>     paths:
>       - '**.js'
> ```

### 在拉取请求合并时运行 `pull_request` 工作流

当拉取请求合并时，拉取请求将自动关闭。 要在拉取请求合并时运行工作流，请使用 `pull_request``closed` 事件类型以及检查事件 `merged` 值的条件。 例如，每当拉取请求关闭时，将运行以下工作流。 仅当拉取请求也合并时，`if_merged` 作业才会运行。

```yaml
on:
  pull_request:
    types:
      - closed

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo The PR was merged
```

#### 存储库分支中的工作流

默认情况下，工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。

除 `GITHUB_TOKEN` 外，当从分支存储库触发工作流时，机密不会传递给运行器。 `GITHUB_TOKEN` 在存储库分支的拉取请求中具有只读权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)”。

#### 复刻的仓库的拉取请求事件

对于从派生仓库到基础仓库的拉取请求，GitHub 会将 `pull_request`、`issue_comment`、`pull_request_review_comment`、`pull_request_review` 和 `pull_request_target` 事件发送到基础仓库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时，拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息，请参阅“[批准来自分支的工作流运行](/zh/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks)”。

对于从分支仓库到专用仓库的拉取请求，工作流仅在启用时运行，请参阅“[管理存储库的GitHub Actions设置](/zh/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)”。

> \[!NOTE]
> Dependabot 拉取请求触发的工作流被视为来自存储库分支，也受到这些限制。

## `pull_request_comment`（使用 `issue_comment`）

要在创建、编辑或删除对拉取请求（而不是拉取请求的差异）的注释时运行工作流，请使用 [`issue_comment`](#issue_comment) 事件。 对于与拉取请求审查或拉取请求审查评论相关的活动，请使用 [`pull_request_review`](#pull_request_review) 或 [`pull_request_review_comment`](#pull_request_review_comment) 事件。

## `pull_request_review`

| Web 挂钩事件有效负载                                                                          | 活动类型                                           | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------ | ------------ |
| [`pull_request_review`](/zh/webhooks/webhook-events-and-payloads#pull_request_review) | - `submitted`<br/>- `edited`<br/>- `dismissed` |              |              |
| `GITHUB_REF` 分支上的最后一次合并提交                                                             | PR 合并分支 `refs/pull/PULL_REQUEST_NUMBER/merge`  |              |              |

> \[!NOTE]
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#pull_request_review)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。

在提交、编辑或关闭拉取请求审阅时运行工作流。 拉取请求审查是除正文评论和状态之外的一组拉取请求审查评论。 对于与拉取请求审查评论或拉取请求评论相关的活动，请改用 [`pull_request_review_comment`](#pull_request_review_comment) 或 [`issue_comment`](#issue_comment) 事件。 有关拉取请求审查 API 的信息，请参阅 GraphQL API 文档中的 [拉取请求](/zh/graphql/reference/pulls#object-pullrequest) 或 [用于拉取请求的 REST API 终结点](/zh/rest/pulls#reviews)。

例如，可以在拉取请求审查的状态为 `edited` 或 `dismissed` 时运行工作流。

```yaml
on:
  pull_request_review:
    types: [edited, dismissed]
```

### 在批准拉取请求时运行工作流

若要在拉取请求获得批准后运行工作流，可以使用 `submitted` 类型的 `pull_request_review` 事件触发工作流，然后使用 `github.event.review.state` 属性检查审查状态。 例如，每当提交拉取请求审查时，此工作流都将运行，但仅当提交的审查是批准审查时，`approved` 作业才会运行：

```yaml
on:
  pull_request_review:
    types: [submitted]

jobs:
  approved:
    if: github.event.review.state == 'approved'
    runs-on: ubuntu-latest
    steps:
      - run: echo "This PR was approved"
```

#### 存储库分支中的工作流

默认情况下，工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。

除 `GITHUB_TOKEN` 外，当从分支存储库触发工作流时，机密不会传递给运行器。 `GITHUB_TOKEN` 在存储库分支的拉取请求中具有只读权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)”。

#### 复刻的仓库的拉取请求事件

对于从派生仓库到基础仓库的拉取请求，GitHub 会将 `pull_request`、`issue_comment`、`pull_request_review_comment`、`pull_request_review` 和 `pull_request_target` 事件发送到基础仓库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时，拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息，请参阅“[批准来自分支的工作流运行](/zh/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks)”。

对于从分支仓库到专用仓库的拉取请求，工作流仅在启用时运行，请参阅“[管理存储库的GitHub Actions设置](/zh/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)”。

> \[!NOTE]
> Dependabot 拉取请求触发的工作流被视为来自存储库分支，也受到这些限制。

## `pull_request_review_comment`

| Web 挂钩事件有效负载                                                                                          | 活动类型                                          | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------ | ------------ |
| [`pull_request_review_comment`](/zh/webhooks/webhook-events-and-payloads#pull_request_review_comment) | - `created`<br/>- `edited`<br/>- `deleted`    |              |              |
| `GITHUB_REF` 分支上的最后一次合并提交                                                                             | PR 合并分支 `refs/pull/PULL_REQUEST_NUMBER/merge` |              |              |

> \[!NOTE]
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#pull_request_review_comment)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。

在修改拉取请求审查评论时运行工作流。 拉取请求审查评论是对拉取请求差异的评论。 对于与拉取请求审查或拉取请求评论相关的活动，请改用 [`pull_request_review`](#pull_request_review) 或 [`issue_comment`](#issue_comment) 事件。 有关拉取请求审查评论 API 的信息，请参阅 GraphQL API 文档中的 [拉取请求](/zh/graphql/reference/pulls#object-pullrequestreviewcomment) 或 [用于拉取请求的 REST API 终结点](/zh/rest/pulls#comments)。

例如，可以在拉取请求审查评论的状态为 `created` 或 `deleted` 时运行工作流。

```yaml
on:
  pull_request_review_comment:
    types: [created, deleted]
```

#### 存储库分支中的工作流

默认情况下，工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。

除 `GITHUB_TOKEN` 外，当从分支存储库触发工作流时，机密不会传递给运行器。 `GITHUB_TOKEN` 在存储库分支的拉取请求中具有只读权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)”。

#### 复刻的仓库的拉取请求事件

对于从派生仓库到基础仓库的拉取请求，GitHub 会将 `pull_request`、`issue_comment`、`pull_request_review_comment`、`pull_request_review` 和 `pull_request_target` 事件发送到基础仓库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时，拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息，请参阅“[批准来自分支的工作流运行](/zh/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks)”。

对于从分支仓库到专用仓库的拉取请求，工作流仅在启用时运行，请参阅“[管理存储库的GitHub Actions设置](/zh/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)”。

> \[!NOTE]
> Dependabot 拉取请求触发的工作流被视为来自存储库分支，也受到这些限制。

## `pull_request_target`

| Web 挂钩事件有效负载                                                            | 活动类型                                                                                                                                                                                                                                                                                                                                                                                                                             | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------ |
|                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                  |              |              |
| [`pull_request`](/zh/webhooks/webhook-events-and-payloads#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `converted_to_draft`<br/>- `locked`<br/>- `unlocked`<br/>- `enqueued`<br/>- `dequeued`<br/>- `milestoned`<br/>- `demilestoned`<br/>- `ready_for_review`<br/>- `review_requested`<br/>- `review_request_removed`<br/>- `auto_merge_enabled`<br/>- `auto_merge_disabled` | 默认分支上的最新提交   | 默认分支         |
|                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                  |              |              |

> \[!NOTE]
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#pull_request)。 默认情况下，工作流仅在 `pull_request_target` 事件的活动类型为 `opened`、`synchronize` 或 `reopened` 时运行。 要按不同的活动类型触发工作流，请使用 `types` 关键字。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。

在工作流存储库中发生有关拉取请求的活动时运行工作流。 例如，如果未指定任何活动类型，则工作流将在打开或重新打开拉取请求时运行，或者在更新拉取请求的头部分支时运行。

就像 拉取请求的基本分支基本存储库的默认分支`pull_request`的上下文中运行，而不是在合并提交的上下文中运行。 这样可以防止从拉取请求的头部执行不安全的代码，以免更改你的存储库或窃取你在工作流中使用的任何机密。 此事件允许你的工作流对来自复刻的拉取请求执行标记或评论等操作。 如果需要从拉取请求构建或运行代码，请避免使用此事件。

为了确保存储库安全性，名称与特定模式匹配（例如类似于 SHA）的分支可能无法使用 `pull_request_target` 事件触发工作流。

> \[!WARNING]
> 在 `pull_request_target` 触发器上运行不受信任的代码可能会导致安全漏洞。 这些漏洞包括缓存中毒以及授予非预期的写入权限或机密访问权限。 若要了解如何安全地使用此触发器，请参阅 [安全地使用 pull\_request\_target](/zh/actions/reference/security/securely-using-pull_request_target)。 有关潜在风险的更多信息，请参阅 GitHub Security Lab 中的 [安全使用指南](/zh/enterprise-cloud@latest/actions/reference/security/secure-use#mitigating-the-risks-of-untrusted-code-checkout) 和 [防范 pwn 请求](https://securitylab.github.com/research/github-actions-preventing-pwn-requests)。

例如，可以在拉取请求的状态为 `assigned`、`opened`、`synchronize` 或 `reopened` 时运行工作流。

```yaml
on:
  pull_request_target:
    types: [assigned, opened, synchronize, reopened]
```

### 基于拉取请求的主要分支或基础分支运行 `pull_request_target` 工作流

可以使用 `branches` 或 `branches-ignore` 筛选器配置工作流，使其仅在面向特定分支的拉取请求上运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore)”。

例如，当有人打开面向名称以 `releases/` 开头的分支的拉取请求时，此工作流将运行：

```yaml
on:
  pull_request_target:
    types:
      - opened
    branches:
      - 'releases/**'
```

> \[!NOTE]
> 如果同时使用 `branches` 筛选器和 `paths` 筛选器，则工作流将只在这两个筛选器都满足条件时运行。 例如，仅当在名称以 `.js` 开头的分支上打开包含 JavaScript (`releases/`) 文件更改的拉取请求时，才会运行以下工作流：
>
> ```yaml
> on:
>   pull_request_target:
>     types:
>       - opened
>     branches:
>       - 'releases/**'
>     paths:
>       - '**.js'
> ```

要基于拉取请求的头部分支名称（而不是拉取请求的基本分支名称）运行作业，请在条件中使用 `github.head_ref` 上下文。 例如，每当打开拉取请求时，此工作流都会运行，但仅当拉取请求的头部是名称以 `run_if` 开头的分支时，才会执行 `releases/` 作业：

```yaml
on:
  pull_request_target:
    types:
      - opened
jobs:
  run_if:
    if: startsWith(github.head_ref, 'releases/')
    runs-on: ubuntu-latest
    steps:
      - run: echo "The head of this PR starts with 'releases/'"
```

### 基于拉取请求中更改的文件运行 `pull_request_target` 工作流

可以使用 `paths` 或 `paths-ignore` 筛选器配置工作流，使其在拉取请求更改特定文件时运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)”。

例如，当拉取请求包含对 JavaScript 文件 (`.js`) 的更改时，此工作流将运行：

```yaml
on:
  pull_request_target:
    paths:
      - '**.js'
```

> \[!NOTE]
> 如果同时使用 `branches` 筛选器和 `paths` 筛选器，则工作流将只在这两个筛选器都满足条件时运行。 例如，仅当在名称以 `.js` 开头的分支上打开包含 JavaScript (`releases/`) 文件更改的拉取请求时，才会运行以下工作流：
>
> ```yaml
> on:
>   pull_request_target:
>     types:
>       - opened
>     branches:
>       - 'releases/**'
>     paths:
>       - '**.js'
> ```

### 在拉取请求合并时运行 `pull_request_target` 工作流

当拉取请求合并时，拉取请求将自动关闭。 要在拉取请求合并时运行工作流，请使用 `pull_request_target``closed` 事件类型以及检查事件 `merged` 值的条件。 例如，每当拉取请求关闭时，将运行以下工作流。 仅当拉取请求也合并时，`if_merged` 作业才会运行。

```yaml
on:
  pull_request_target:
    types:
      - closed

jobs:
  if_merged:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo The PR was merged
```

## `push`

| Web 挂钩事件有效负载                                            | 活动类型 | `GITHUB_SHA`                                          | `GITHUB_REF` |
| ------------------------------------------------------- | ---- | ----------------------------------------------------- | ------------ |
| [`push`](/zh/webhooks/webhook-events-and-payloads#push) | 不适用  | 提示提交已推送至参考。删除分支时，工作流运行中的 SHA（及其关联的 refs）将恢复为存储库的默认分支。 | 更新的引用        |

> \[!NOTE]
>
> * 可用于GitHub Actions的 Webhook 有效负载不包括 `added`、`removed` 和 `modified` 对象中的 `commit` 属性。 你可以使用 API 检索完整的提交对象。 有关详细信息，请参阅 GraphQL API 文档中的 [提交](/zh/graphql/reference/commits#object-commit) 或 [REST API 提交端点](/zh/rest/commits#get-a-commit)。
> * 如果一次推送 5,000 个以上的分支，则不会创建事件。 一次推送三个以上的标记时，不会为标记创建事件。

在推送提交或标记或使用模板创建存储库时运行工作流。 这包括未合并到默认分支中的工作流。 有关详细信息，请参阅“[触发工作流的事件](/zh/actions/reference/workflows-and-actions/events-that-trigger-workflows#running-your-workflow-only-when-a-push-to-specific-branches-occurs)”。

例如，可以在发生 `push` 事件时运行工作流。

```yaml
on:
  push
```

> \[!NOTE]
> 当 `push` Webhook 事件触发工作流运行时，操作 UI 的“推送者”字段会显示推送者的帐户，而不是作者或提交者的帐户。 但是，如果使用带有部署密钥的 SSH 身份验证将更改推送到存储库，则“推送者”字段将是在将部署密钥添加到存储库时验证部署密钥的存储库管理员。

### 仅在推送到特定分支时运行工作流

可以使用 `branches` 或 `branches-ignore` 筛选器配置工作流，使其仅在推送特定分支时运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushbranchestagsbranches-ignoretags-ignore)”。

例如，当有人推送到 `main` 或推送到以 `releases/` 开头的分支时，此工作流将运行。

```yaml
on:
  push:
    branches:
      - 'main'
      - 'releases/**'
```

> \[!NOTE]
> 如果同时使用 `branches` 筛选器和 `paths` 筛选器，则工作流将只在这两个筛选器都满足条件时运行。 例如，仅当推送包含 JavaScript（`.js`）文件的更改，且该推送目标为名称以 `releases/`开头的分支时，以下工作流才会运行：
>
> ```yaml
> on:
>   push:
>     branches:
>       - 'releases/**'
>     paths:
>       - '**.js'
> ```

### 仅在发生特定标记的推送时运行工作流

可以使用 `tags` 或 `tags-ignore` 筛选器配置工作流，使其仅在推送特定标记时运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushbranchestagsbranches-ignoretags-ignore)”。

例如，当有人推送以 `v1.` 开头的标记时，此工作流将运行。

```yaml
on:
  push:
    tags:
      - v1.**
```

### 仅当推送影响特定文件时才运行工作流

可以使用 `paths` 或 `paths-ignore` 筛选器配置工作流，使其在推送到特定文件时运行。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)”。

例如，当有人将更改推送到 JavaScript 文件 (`.js`) 时，此工作流将运行：

```yaml
on:
  push:
    paths:
      - '**.js'
```

## `registry_package`

| Web 挂钩事件有效负载                                                           | 活动类型                          | `GITHUB_SHA` | `GITHUB_REF` |
| ---------------------------------------------------------------------- | ----------------------------- | ------------ | ------------ |
| [`registry_package`](/zh/webhooks/webhook-events-and-payloads#package) | - `published`<br/>- `updated` | 提交已发布的包      | 已发布软件包的分支或标签 |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#registry_package)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * 推送多体系结构容器映像时，每个清单都会发生一次此事件，因此你可能会观察到工作流触发多次。 若要缓解此问题，并且仅为包含实际图像标记信息的事件运行工作流作业，请使用条件：
>
> ```yaml
> jobs:
>     job_name:
>         if: $true
> ```

在存储库中发生与 GitHub Packages 相关的活动时运行工作流。 有关详细信息，请参阅 [GitHub Packages 文档](/zh/packages)。

例如，可以在新包版本状态为 `published` 时运行工作流。

```yaml
on:
  registry_package:
    types: [published]
```

## `release`

| Web 挂钩事件有效负载                                                  | 活动类型                                                                                                                        | `GITHUB_SHA` | `GITHUB_REF`                   |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------ |
| [`release`](/zh/webhooks/webhook-events-and-payloads#release) | - `published` <br/>- `unpublished` <br/>- `created` <br/>- `edited` <br/>- `deleted` <br/>- `prereleased`<br/> - `released` | 标记的发行版中的最新提交 | 版本的标记参考 `refs/tags/<tag_name>` |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#release)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 草稿版本的 `created`、`edited` 或 `deleted` 活动类型不会触发工作流。 通过 GitHub UI 创建发布时，你的版本可能会自动保存为草稿。
> * 对于从草稿版本发布的预发行版本，`prereleased` 类型不会触发工作流，但 `published` 类型会触发。 如果想要在稳定版\_和\_预发行版发布时运行工作流，请订阅 `published` 而不是 `released` 和 `prereleased`。

在存储库中发生发布活动时运行工作流。 有关版本 API 的信息，请参阅 GraphQL API 文档中的 [Releases](/zh/graphql/reference/releases#object-release) 或 REST API 文档中的 [发布和发布资产的 REST API 终结点](/zh/rest/releases)。

例如，可以在版本状态为 `published` 时运行工作流。

```yaml
on:
  release:
    types: [published]
```

## `repository_dispatch`

| Web 挂钩事件有效负载                                                                         | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ------------------------------------------------------------------------------------ | ---- | ------------ | ------------ |
| [repository\_dispatch](/zh/webhooks/webhook-events-and-payloads#repository_dispatch) | 自定义  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

当您想要为 GitHub 之外发生的活动触发工作流时，可以使用 `repository_dispatch` API 来触发一个名为 [](/zh/webhooks/webhook-events-and-payloads#repository_dispatch) 的 Webhook 事件。 有关详细信息，请参阅“[存储库的 REST API 终结点](/zh/rest/repos/repos#create-a-repository-dispatch-event)”。

发出创建 `repository_dispatch` 事件的请求时，必须指定 `event_type` 来描述活动类型。 默认情况下，所有 `repository_dispatch` 活动类型都会触发一个工作流运行。 可以使用 `types` 关键字限制工作流，使其在 `event_type` Webhook 有效负载中发送特定 `repository_dispatch` 值时运行。

```yaml
on:
  repository_dispatch:
    types: [test_result]
```

> \[!NOTE]
> `event_type` 值仅限 100 个字符。

通过 `client_payload` 参数发送的任何数据都将在工作流的 `github.event` 上下文中可用。 例如，如果在创建存储库调度事件时发送此请求正文：

```json
{
  "event_type": "test_result",
  "client_payload": {
    "passed": false,
    "message": "Error: timeout"
  }
}
```

则你可以在如下工作流中访问有效负载：

```yaml
on:
  repository_dispatch:
    types: [test_result]

jobs:
  run_if_failure:
    if: ${{ !github.event.client_payload.passed }}
    runs-on: ubuntu-latest
    steps:
      - env:
          MESSAGE: ${{ github.event.client_payload.message }}
        run: echo $MESSAGE
```

> \[!NOTE]
> \*
> `client_payload` 中顶级属性的最大数目为 10。
>
> * 有效负载最多可包含 65,535 个字符。

## `schedule`

| Web 挂钩事件有效负载 | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ------------ | ---- | ------------ | ------------ |
| 不适用          | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
>
> * `schedule` 事件在 GitHub Actions 工作流运行期间负载过高时可能会延迟。 高负载时间包括每小时的开始时间。 如果负载足够高，可能会删除一些排队作业。 为了降低延迟的可能性，将您的工作流程安排在不同时间运行。
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * 计划的工作流将仅在默认分支上运行。
> * 在公共存储库中，当 60 天内未发生存储库活动时，将自动禁用计划的工作流。 有关重新启用已禁用的工作流的信息，请参阅“[禁用和启用工作流](/zh/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows#enabling-a-workflow)”。

通过 `schedule` 事件，可以在计划的时间触发工作流。

**Example:**

```yaml
 on:
   schedule:
     - cron: "15 4,5 * * *"
```

使用 [POSIX cron 语法](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) 计划工作流在特定时间运行。 默认情况下，计划的工作流以 UTC 方式运行。 可以选择使用 [IANA 时区字符串](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 指定时区，以便进行时区感知计划。 计划的工作流在默认分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。

> \[!NOTE]
> 对于设置为 `timezone` 观察夏令时（DST）的时区（DST）的计划，在 DST 春季前移转换期间，计划工作流将提前数小时前进到下一个有效时间。 例如，上午 2：30 的计划将提前到凌晨 3：00。

计划任务语法有五个字段，中间用空格分隔，每个字段代表一个时间单位。

```text
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
* * * * *
```

你可在这五个字段中使用以下运算符：

| 运算符                                                              | 说明     | 示例 |
| ---------------------------------------------------------------- | ------ | -- |
| \*                                                               | 任何值    |    |
| `15 * * * *` 在每天每小时的每个第 15 分钟运行。                                 |        |    |
| "                                                                | 值列表分隔符 |    |
| `2,10 4,5 * * *` 在每天第 4 和第 5 小时的第 2 和第 10 分钟运行。                  |        |    |
| -                                                                | 值的范围   |    |
| `30 4-6 * * *` 在第 4、5 和 6 小时的第 30 分钟运行。                          |        |    |
| /                                                                | 步骤值    |    |
| `20/15 * * * *` 从第 20 分钟到第 59 分钟之间每隔 15 分钟运行一次（第 20、35 和 50 分钟）。 |        |    |

本示例触发工作流在美国/纽约时区每周一到周五的凌晨5:30运行。

```yaml
on:
  schedule:
    - cron: '30 5 * * 1-5'
      timezone: "America/New_York"
```

多个 `schedule` 事件可以触发单个工作流。 通过 `schedule` 上下文访问触发工作流的 `github.event.schedule` 事件。 此示例触发工作流在每周一至周四 UTC 时间 5:30 以及周二和周四 UTC 时间 17:30 运行，但在周一和周三跳过 `Not on Monday or Wednesday` 步骤。

```yaml
on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5,17 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"
```

> \[!NOTE]
> GitHub Actions不支持非标准语法`@yearly`、`@monthly`、`@weekly`、`@daily``@hourly`和`@reboot`。

可以使用 [crontab guru](https://crontab.guru/) 帮助生成 cron 语法并确认其运行时间。 为了帮助入门，我们还提供了 [crontab guru 示例](https://crontab.guru/examples.html)列表。

### 计划工作流的 `actor`

某些存储库事件会更改与工作流关联的 `actor`。 例如，更改存储库默认分支（这会更改计划工作流的运行分支）的用户将成为这些计划工作流的 `actor`。

对于已停用的计划工作流，如果对存储库拥有 `write` 权限的用户进行一个更改工作流上的 `cron` 计划的提交，则该工作流将被重新激活，并且该用户将成为与任何工作流运行关联的 `actor`。

计划工作流的通知将发送给最后修改工作流文件中的 cron 语法的用户。 有关详细信息，请参阅“[工作流程运行通知](/zh/actions/concepts/workflows-and-actions/notifications-for-workflow-runs)”。

> \[!NOTE]
> 对于具有 Enterprise Managed Users计划工作流的企业，触发计划工作流要求与工作流关联的用户帐户的状态 `actor` 当前处于活动状态（即未暂停或删除）。
>
> * 如果 `actor` 标识提供程序 (IdP) 已取消预配与计划工作流关联的最后一个 Enterprise Managed User，则该计划工作流将不会运行。 但是，如果 IdP 尚未取消预配最后一个`actor`Enterprise Managed User，而仅仅是将该用户从企业中的某个组织的成员列表中删除，则计划工作流仍将运行，并将该用户设置为`actor`。
> * 同样，对于没有Enterprise Managed Users的企业来说，从组织中删除一个用户不会阻止那些计划中以该用户为`actor`的工作流的运行。
> * 因此，*用户帐户\_的状态在Enterprise Managed User和非Enterprise Managed User方案中都很重要，而非计划工作流所在组织中的用户\_成员身份状态*。

## `status`

| Web 挂钩事件有效负载                                                | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------- | ---- | ------------ | ------------ |
| [`status`](/zh/webhooks/webhook-events-and-payloads#status) | 不适用  | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在 Git 提交状态更改时运行工作流。 例如，可以将提交标记为 `error`、`failure`、`pending` 或 `success`。 如果要提供有关状态更改的更多详细信息，可能需要使用 [`check_run`](#check_run) 事件。 有关提交状态 API 的信息，请参阅 GraphQL API 文档中的 [提交](/zh/graphql/reference/commits#object-status) 或 [REST API 提交端点](/zh/rest/commits#commit-statuses)。

例如，可以在发生 `status` 事件时运行工作流。

```yaml
on:
  status
```

如果要基于新的提交状态在工作流中运行作业，可以使用 `github.event.state` 上下文。 例如，以下工作流在提交状态发生更改时触发，但 `if_error_or_failure` 作业仅在新的提交状态为 `error` 或 `failure` 时才运行。

```yaml
on:
  status
jobs:
  if_error_or_failure:
    runs-on: ubuntu-latest
    if: >-
      github.event.state == 'error' ||
      github.event.state == 'failure'
    steps:
      - env:
          DESCRIPTION: ${{ github.event.description }}
        run: |
          echo The status is error or failed: $DESCRIPTION
```

## `watch`

| Web 挂钩事件有效负载                                              | 活动类型        | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------------------------------------------- | ----------- | ------------ | ------------ |
| [`watch`](/zh/webhooks/webhook-events-and-payloads#watch) | - `started` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 尽管仅 `started` 支持活动类型，但如果将来添加更多活动类型，则指定活动类型将保留工作流的特定状态。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#watch)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

在工作流的存储库加星标时运行工作流。 有关拉取请求 API 的信息，请参阅 GraphQL API 文档中的 [Activity](/zh/graphql/reference/activity#mutation-addstar) 或 [标星的 REST API 端点](/zh/rest/activity/starring)。

例如，可以在某人为存储库加星标时（即监视事件的 `started` 活动类型）运行工作流。

```yaml
on:
  watch:
    types: [started]
```

## `workflow_call`

| Web 挂钩事件有效负载 | 活动类型 | `GITHUB_SHA` | `GITHUB_REF` |
| ------------ | ---- | ------------ | ------------ |
| 与调用方工作流相同    | 不适用  | 与调用方工作流相同    | 与调用方工作流相同    |

`workflow_call` 用于指示一个工作流可以由另一个工作流调用。 当使用 `workflow_call` 事件触发工作流时，被调用工作流中的事件负载与调用工作流中的事件负载相同。 有关详细信息，请参阅“[重用工作流](/zh/actions/how-tos/reuse-automations/reuse-workflows)”。

以下示例仅在从另一个工作流调用时运行工作流：

```yaml
on: workflow_call
```

## `workflow_dispatch`

| Web 挂钩事件有效负载                                                                     | 活动类型       | `GITHUB_SHA` | `GITHUB_REF` |
| -------------------------------------------------------------------------------- | ---------- | ------------ | ------------ |
| [workflow\_dispatch](/zh/webhooks/webhook-events-and-payloads#workflow_dispatch) | 不适用        |              |              |
| `GITHUB_REF` 分支或标记上的最后一次提交                                                       | 收到调度的分支或标记 |              |              |

> \[!NOTE]
> 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

若要启用手动触发工作流，需要配置 `workflow_dispatch` 事件。 可以使用 GitHub API、GitHub CLI 或 GitHub UI 手动触发工作流运行。 有关详细信息，请参阅“[手动运行工作流](/zh/actions/how-tos/manage-workflow-runs/manually-run-a-workflow)”。

```yaml
on: workflow_dispatch
```

### 提供输入

你可以直接在工作流中配置事件的自定义输入属性、默认输入值和必要输入。 触发事件时，可以提供 `ref` 和任何 `inputs`。 当工作流运行时，你可以访问 `inputs` 上下文中的输入值。 有关详细信息，请参阅“[上下文参考](/zh/actions/reference/workflows-and-actions/contexts)”。

> \[!NOTE]
>
> * 工作流还将接收 `github.event.inputs` 上下文中的输入。
>   `inputs` 上下文和 `github.event.inputs` 上下文中的信息完全相同，但 `inputs` 上下文将布尔值保留为布尔值，而不是将它们转换为字符串。
>   `choice` 类型解析为字符串，是单个可选选项。
> * 顶级属性 `inputs` 的最大数目为 25 。
> *

`inputs` 的最大有效负载为 65,535 个字符。

此示例定义了名为 `logLevel`、`tags` 和 `environment` 的输入。 在运行工作流时，可以将这些输入的值传递给工作流。 然后，此工作流使用 `inputs.logLevel`、`inputs.tags` 和 `inputs.environment` 上下文属性将值输出到日志。

```yaml
on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
        - info
        - warning
        - debug
      tags:
        description: 'Test scenario tags'
        required: false
        type: boolean
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  log-the-inputs:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Log level: $LEVEL"
          echo "Tags: $TAGS"
          echo "Environment: $ENVIRONMENT"
        env:
          LEVEL: ${{ inputs.logLevel }}
          TAGS: ${{ inputs.tags }}
          ENVIRONMENT: ${{ inputs.environment }}
```

如果从浏览器运行此工作流，则必须在工作流运行之前手动输入所需输入的值。

![工作流运行列表的屏幕截图。 标有“运行工作流”并展开以显示输入字段的下拉菜单以深橙色轮廓显示。](/assets/images/help/actions/workflow-dispatch-inputs.png)

在从脚本运行工作流或使用 GitHub CLI 时，可以传递输入。 举例来说：

```shell
gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=staging
```

有关详细信息，请参阅 GitHub CLI[手动运行工作流](/zh/actions/how-tos/manage-workflow-runs/manually-run-a-workflow) 中的信息。

## `workflow_run`

| Web 挂钩事件有效负载                                                            | 活动类型                                                | `GITHUB_SHA` | `GITHUB_REF` |
| ----------------------------------------------------------------------- | --------------------------------------------------- | ------------ | ------------ |
| [`workflow_run`](/zh/webhooks/webhook-events-and-payloads#workflow_run) | - `completed`<br/>- `requested`<br/>- `in_progress` | 默认分支上的最新提交   | 默认分支         |

> \[!NOTE]
> \*
> 多个活动类型会触发此事件。 重新运行工作流时，`requested` 活动类型不会发生。 有关每个活动类型的信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads#workflow_run)。 默认情况下，所有活动类型都会触发在此事件上运行的工作流。 你可以使用 `types` 关键词将工作流运行限制为特定活动类型。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)”。
>
> * 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。
> * 不能使用 `workflow_run` 将超过三个工作流级别链接在一起。 例如，如果尝试触发五个工作流（名为 `B` 至 `F`）在初始工作流 `A` 运行后依次运行（即：`A` → `B` → `C` → `D` → `E` → `F`），工作流 `E` 和 `F` 将不会运行。

此事件在请求或完成工作流运行时发生。 它允许你基于另一个工作流的执行或完成来执行工作流。 由 `workflow_run` 事件启动的工作流能够访问机密和写入令牌，即使以前的工作流不能访问也是如此。 这在以前的工作流有意未获权限的情况下很有用，但你需要在以后的工作流中采取特权行动。

> \[!WARNING]
> 在 `workflow_run` 触发器上运行不受信任的代码可能会导致安全漏洞。 这些漏洞包括缓存中毒以及授予非预期的写入权限或机密访问权限。 有关详细信息，请参阅 GitHub Enterprise Cloud 文档中的 [安全使用指南](/zh/enterprise-cloud@latest/actions/reference/security/secure-use#mitigating-the-risks-of-untrusted-code-checkout) 以及 GitHub Security Lab 网站上的[防止 pwn 请求](https://securitylab.github.com/research/github-actions-preventing-pwn-requests)。

在此示例中，工作流配置为在单独的“运行测试”工作流完成后运行。

```yaml
on:
  workflow_run:
    workflows: [Run Tests]
    types:
      - completed
```

如果为 `workflows` 事件指定多个 `workflow_run`，则只需要运行其中一个工作流。 例如，具有以下触发器的工作流将在 "Staging" 工作流或 "Lab" 工作流完成时运行。

```yaml
on:
  workflow_run:
    workflows: [Staging, Lab]
    types:
      - completed
```

### 基于另一个工作流的结果运行工作流

无论上一个工作流的结果如何，工作流运行都会被触发。 如果要基于触发工作流的结果运行作业或步骤，则可以使用带有 `github.event.workflow_run.conclusion` 属性的条件。 例如，每当名为“Build”的工作流完成时，此工作流就会运行，但 `on-success` 作业仅在“Build”工作流成功时才会运行，而 `on-failure` 作业仅在“Build”工作流失败时才会运行：

```yaml
on:
  workflow_run:
    workflows: [Build]
    types: [completed]

jobs:
  on-success:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - run: echo 'The triggering workflow passed'
  on-failure:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - run: echo 'The triggering workflow failed'
```

### 将工作流限于基于分支的运行

可以使用 `branches` 或 `branches-ignore` 筛选器，指定触发工作流必须在哪些分支上运行才能触发工作流。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_runbranchesbranches-ignore)”。 例如，仅当名为 `Build` 的工作流在名为 `canary` 的分支上运行时，具有以下触发器的工作流才会运行。

```yaml
on:
  workflow_run:
    workflows: [Build]
    types: [requested]
    branches: [canary]
```

### 使用触发工作流中的数据

可以访问与触发工作流的工作流对应的[`workflow_run`事件负载](/zh/webhooks/webhook-events-and-payloads#workflow_run)。 例如，如果触发工作流生成项目，则使用 `workflow_run` 事件触发的工作流可以访问这些项目。

以下工作流将数据作为构件上传。 （在此简化的示例中，数据是拉取请求编号。）

```yaml
name: Upload data

on:
  pull_request:

jobs:
  upload:
    runs-on: ubuntu-latest

    steps:
      - name: Save PR number
        env:
          PR_NUMBER: ${{ github.event.number }}
        run: |
          mkdir -p ./pr
          echo $PR_NUMBER > ./pr/pr_number
      - uses: actions/upload-artifact@v4
        with:
          name: pr_number
          path: pr/
```

当上述工作流的运行完成时，它将触发以下工作流的运行。 以下工作流使用 `github.event.workflow_run` 上下文和 actions/download-artifact\@v5 操作，下载由上述工作流上传的工件，然后对作为工件上传的拉取请求编号进行评论。

```yaml
name: Use the data

on:
  workflow_run:
    workflows: [Upload data]
    types:
      - completed

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - name: 'Download artifact'
        uses: actions/download-artifact@v5
        with:
          name: pr_number
          # do not extract in the workspace dir that may contain executable scripts
          path: ${{ runner.temp }}/artifacts
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: 'Comment on PR'
        uses: actions/github-script@v8
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fs = require('fs');
            const path = require('path');
            const temp = '${{ runner.temp }}/artifacts';
            const issue_number_raw = fs.readFileSync(path.join(temp, 'pr_number'), 'utf8').trim();
            const issue_number = Number(issue_number_raw);
            if (!Number.isInteger(issue_number)) {
              throw new Error(`Invalid PR number in pr_number artifact: "${issue_number_raw}"`);
            }
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: issue_number,
              body: 'Thank you for the PR!'
            });
```