触发工作流程的事件

以下步骤将触发工作流程运行：

1. 仓库中发生事件，生成的事件具有关联的提交 SHA 和 Git ref。

2. 在仓库的 .github/workflow 目录中关联的提交 SHA 或 Git ref 处搜索工作流程文件。 工作流程文件必须存在于该提交 SHA 或 Git ref 中才会被考虑。

   例如，如果事件发生在特定仓库分支上，则工作流程文件必须存在于该分支的仓库中。

3. 检查该提交 SHA 和 Git ref 的工作流程文件， 并且对其 on: 值与触发事件匹配的任何工作流程触发新的工作流程。

   工作流程在触发事件的相同提交 SHA 和 Git ref 上的仓库代码中运行。 当工作流程运行时，GitHub 会在运行器环境中设置 GITHUB_SHA（提交 SHA）和 GITHUB_REF（Git 引用）环境变量。 更多信息请参阅“使用环境变量”。

安排的事件

schedule 事件允许您在计划的时间触发工作流程。

计划

您可以使用 POSIX cron 语法安排工作流程在特定的 UTC 时间运行。 预定的工作流程在默认或基础分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。

此示例在每天 5:30 和 17:30 UTC 触发工作流程：

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

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

┌───────────── 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)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

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

您可以使用 crontab guru 帮助生成计划任务语法并确认它在何时运行。 为帮助您开始，我们还提供了一系列 crontab guru 示例。

计划工作流程的通知将发送给最后修改工作流程文件中的 cron 语法的用户。 更多信息请参阅“工作流程运行通知”。

手动事件

您可以手动触发工作流程运行。 要触发仓库中的特定工作流程，请使用 workflow_dispatch 事件。 要触发仓库中的多个工作流程并创建自定义事件和事件类型，请使用 repository_dispatch 事件。

workflow_dispatch

您可以直接在工作流程中配置事件的自定义输入属性、默认输入值和必要输入。 当工作流程运行时，您可以访问 github.event.inputs 上下文中的输入值。 更多信息请参阅“上下文”。

您可以使用 GitHub API 以及从 GitHub 手动触发工作流程运行。 更多信息请参阅“手动配置工作流程。

当您在 GitHub 上触发事件时，可以在 GitHub 上直接提供 ref 和任何 inputs。 更多信息请参阅“对操作使用输入和输出”。

要使用 REST API 触发自定义 workflow_dispatch web 挂钩事件，您必须发送 POST 请求到 GitHub API 端点，并提供 ref 和任何必要的 inputs。 更多信息请参阅“创建工作流程调度事件”REST API 端点。

示例

要使用 Workflow_paid 事件，您需要将其作为触发器包含在您的 GitHub Actions 工作流程文件中。 下面的示例仅在手动触发时运行工作流程：

on: workflow_dispatch

示例工作流程配置

此示例定义了 name 和 home 输入，并使用 github.event.inputs.name 和 github.event.inputs.home 上下文打印。 如果未提供 home ，则打印默认值“The Octoverse”。

name: Manually triggered workflow
on:
  workflow_dispatch:
    inputs:
      name:
        description: 'Person to greet'
        required: true
        default: 'Mona the Octocat'
      home:
        description: 'location'
        required: false
        default: 'The Octoverse'

jobs:
  say_hello:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Hello ${{ github.event.inputs.name }}!"
          echo "- in ${{ github.event.inputs.home }}!"

repository_dispatch

当您想要触发在 GitHub 外发生的活动的工作流程时，可以使用 GitHub API 触发名为 repository_dispatch 的 web 挂钩事件。 更多信息请参阅“创建仓库调度事件”。

要触发自定义 repository_dispatch web 挂钩事件，必须将 POST 请求发送到 GitHub API 端点，并提供 event_type 名称来描述活动类型。 要触发工作流程运行，还必须配置工作流程使用 repository_dispatch 事件。

示例

默认情况下，所有 event_types 都会触发工作流程运行。 您可以限制工作流程在 repository_dispatch web 挂钩有效负载中发送特定 event_type 值时运行。 创建仓库调度事件时定义在 repository_dispatch 有效负载中发送的事件类型。

on:
  repository_dispatch:
    types: [opened, deleted]

Web 挂钩事件

您可以将工作流程配置为在 GitHub 上生成 web 挂钩事件时运行。 某些事件有多种触发事件的活动类型。 如果有多种活动类型触发事件，则可以指定哪些活动类型将触发工作流程运行。 更多信息请参阅“web 挂钩”。

并非所有 web 挂钩事件都触发工作流程。 要了解可用 web 挂钩事件及其有效负载的完整列表，请参阅“web 挂钩事件和有效负载”。

check_run

在发生 check_run 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“检查运行”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在检查运行为 rerequested 或 completed 时运行工作流程。

on:
  check_run:
    types: [rerequested, completed]

check_suite

在发生 check_suite 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“检查套件”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在检查套件为 rerequested 或 completed 时运行工作流程。

on:
  check_suite:
    types: [rerequested, completed]

create

每当有人创建分支或标记（触发 create 事件）时运行您的工作流程。 有关 REST API 的信息，请参阅“创建引用”。

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

on:
  create

delete

每当有人删除分支或标记（触发 delete 事件）时运行您的工作流程。 有关 REST API 的信息，请参阅“删除引用”。

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

on:
  delete

deployment

每当有人创建部署（触发 deployment 事件）时运行您的工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。 有关 REST API 的信息，请参阅“部署”。

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

on:
  deployment

deployment_status

每当第三方提供部署状态（触发 deployment_status 事件）时运行您的工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。 有关 REST API 的信息，请参阅“创建部署状态”。

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

on:
  deployment_status

讨论

在发生 discussion 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 GraphQL API 的信息，请参阅“讨论”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

For example, you can run a workflow when a discussion has been created, edited, or answered.

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

discussion_comment

在发生 discussion_comment 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 GraphQL API 的信息，请参阅“讨论”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在议题评论为 created 或 deleted 时运行工作流程。

on:
  discussion_comment:
    types: [created, deleted]

复刻

每当有人复刻仓库（触发 fork 事件）时运行您的工作流程。 有关 REST API 的信息，请参阅“创建复刻”。

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

on:
  fork

gollum

当有人创建或更新 Wiki 页面时（触发 gollum 事件）运行您的工作流程。

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

on:
  gollum

issue_comment

在发生 issue_comment 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“议题评论”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在议题评论为 created 或 deleted 时运行工作流程。

on:
  issue_comment:
    types: [created, deleted]

issue_comment 事件在评论问题和拉取请求时发生。 要确定 issue_comment 事件是否从议题或拉取请求触发，可以检查 issue.pull_request 属性的事件有效负载，并使用它作为跳过作业的条件。

例如，您可以选择在拉取请求中发生评论事件时运行 pr_commented 作业，在议题中发生评论事件时运行 issue_commented 作业。

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 "Comment on PR #${{ 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 "Comment on issue #${{ github.event.issue.number }}"

议题

在发生 issues 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“议题”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在议题为 opened、edited 或 milestoned 时运行工作流程。

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

标签

在发生 label 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“标签”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在标签为 created 或 deleted 时运行工作流程。

on:
  label:
    types: [created, deleted]

里程碑

在发生 milestone 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“里程碑”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

on:
  milestone:
    types: [opened, deleted]

page_build

在有人推送到启用 GitHub Pages 的分支（触发 page_build 事件）的任何时间运行您的工作流程。 有关 REST API 的信息，请参阅“页面”。

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

on:
  page_build

project

在发生 project 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“项目”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在项目为 created 或 deleted 时运行工作流程。

on:
  project:
    types: [created, deleted]

project_card

在发生 project_card 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“项目卡”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在项目卡为 opened 或 deleted 时运行工作流程。

on:
  project_card:
    types: [created, deleted]

project_column

在发生 project_column 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“项目列”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在项目列为 created 或 deleted 时运行工作流程。

on:
  project_column:
    types: [created, deleted]

public

每当有人将私有仓库公开（触发 public 事件）时运行您的工作流程。 有关 REST API 的信息，请参阅“编辑仓库”。

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

on:
  public

pull_request

在发生 pull_request 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“拉取请求”。

您可以使用 types 关键词扩展或限制默认活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

on:
  pull_request:
    types: [assigned, opened, synchronize, reopened]

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

当创建一个从复刻仓库到基础仓库的拉取请求时，GitHub 发送 pull_request 事件到基础仓库，而在复刻仓库上不发生拉取请求事件。

默认情况下，工作流程不在复刻仓库上运行。 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

当贡献者第一次向公共仓库提交拉取请求时，拥有写入权限的维护者可能需要批准拉取请求上运行的工作流程。 更多信息请参阅“批准公共复刻中的工作流程运行”。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 对复刻仓库中 GITHUB_TOKEN 的权限是只读的。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

pull_request_review

在发生 pull_request_review 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“拉取请求审查”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在拉取请求审查为 edited 或 dismissed 时运行工作流程。

on:
  pull_request_review:
    types: [edited, dismissed]

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

当创建一个从复刻仓库到基础仓库的拉取请求时，GitHub 发送 pull_request 事件到基础仓库，而在复刻仓库上不发生拉取请求事件。

默认情况下，工作流程不在复刻仓库上运行。 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

当贡献者第一次向公共仓库提交拉取请求时，拥有写入权限的维护者可能需要批准拉取请求上运行的工作流程。 更多信息请参阅“批准公共复刻中的工作流程运行”。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 对复刻仓库中 GITHUB_TOKEN 的权限是只读的。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

pull_request_review_comment

每当拉取请求统一差异的评论被修改（触发 pull_request_review_comment 事件）时运行您的工作流程。 多个活动类型会触发此事件。 有关 REST API 的信息，请参阅“审查评论”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

on:
  pull_request_review_comment:
    types: [created, deleted]

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

当创建一个从复刻仓库到基础仓库的拉取请求时，GitHub 发送 pull_request 事件到基础仓库，而在复刻仓库上不发生拉取请求事件。

默认情况下，工作流程不在复刻仓库上运行。 您必须在复刻仓库的 Actions（操作）选项卡中启用 GitHub Actions。

当贡献者第一次向公共仓库提交拉取请求时，拥有写入权限的维护者可能需要批准拉取请求上运行的工作流程。 更多信息请参阅“批准公共复刻中的工作流程运行”。

除了 GITHUB_TOKEN 以外，从复刻的仓库触发工作流程时密码不会传递给运行程序。 对复刻仓库中 GITHUB_TOKEN 的权限是只读的。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

pull_request_target

此事件在拉取请求基础的上下文中运行，而不是像 pull_request 事件一样在合并提交中运行。 这样可以防止从拉取请求的头部执行不安全的工作流程代码，以免更改您的仓库或窃取您在工作流程中使用的任何机密。 此事件允许您根据事件有效负载的内容创建工作流程来标识和评论拉取请求，等等。

默认情况下，工作流程仅在 pull_request_target 的活动类型为 opened、synchronize 或 reopened 时运行。 要让更多活动类型触发工作流程，请使用 types 关键词。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

推送

有人向仓库分支推送（触发 push 事件）时运行您的工作流程。

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

on:
  push

registry_package

只要软件包为 published or updated，即运行工作流程。 更多信息请参阅“使用 GitHub Packages 管理包”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在软件包为 published 时运行工作流程。

on:
  registry_package:
    types: [published]

发行版

在发生 release 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“发行版”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在版本发布为 published 时运行工作流程。

on:
  release:
    types: [published]

状态

在 Git 提交的状态发生变化（触发 status 事件）的任何时间运行您的工作流程。 有关 REST API 的信息，请参阅“状态”。

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

on:
  status

查看

在发生 watch 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。有关 REST API 的信息，请参阅“星标”。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

例如，您可以在某人为仓库加星标时（即触发关注事件的 started 活动类型）运行工作流程。

on:
  watch:
    types: [started]

workflow_run

当请求或完成工作流程运行时，将发生此事件，并允许您基于另一个工作流程的完成结果执行工作流程。 无论上一个工作流程的结果如何，工作流程运行都会被触发。

例如，如果 pull_request 工作流程生成构件，您可以创建一个使用 workflow_run 来分析结果的新工作流程，并向原始拉取请求添加注释。

由 workflow_run 事件启动的工作流程能够访问密钥和写入令牌，即使以前的工作流程不能访问也一样。 这在以前的工作流程有意未获权限的情况下很有用，但您需要在以后的工作流程中采取特权行动。

默认情况下，所有活动类型都会触发一个工作流程。 您可以使用 types（类型） 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

如果需要从此事件中筛选分支，可以使用 branches 或 branches-ignore。

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

on:
  workflow_run:
    workflows: ["Run Tests"]
    branches: [main]
    types: 
      - completed
      - requested

要根据上次工作流程运行的结果有条件地运行工作流程作业，您可以使用 jobs.<job_id>.if 或 jobs.<job_id>.steps[*].if 有条件地结合上次运行的结论。 例如：

on:
  workflow_run:
    workflows: ["Build"]
    types: [completed]

jobs:
  on-success:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      ...
  on-failure:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      ...

使用个人访问令牌触发新工作流程

使用仓库的 GITHUB_TOKEN 代表 GitHub Actions 应用程序执行任务时，GITHUB_TOKEN 触发的事件不会创建新的工作流程运行。 这可以防止意外创建递归工作流程运行。 例如，如果工作流程运行使用仓库的 GITHUB_TOKEN 推送代码，则即使仓库包含配置为在 push 事件发生时运行的工作流程，新工作流程也不会运行。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

如果要从工作流程运行触发工作流程，您可以使用个人访问令牌触发事件。 您需要创建个人访问令牌并将其存储为密码。 为了最大限度地降低 GitHub Actions 使用成本，请确保不要创建递归或意外的工作流程。 有关存储个人访问令牌的更多信息，请参阅“创建和存储加密密码”。