👋 We've unified all of GitHub's product documentation in one place! Check out the content for REST API, GraphQL API, and Developers. Learn more on the GitHub blog.


我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

触发工作流程的事件

您可以配置工作流程在 GitHub 上发生特定活动时运行、在预定的时间运行,或者在 GitHub 外部的事件发生时运行。

GitHub 操作 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub 操作 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 更多信息请参阅“GitHub 的产品”。

本文内容

关于工作流程事件

您可以配置工作流程在 web 挂钩事件从 GitHub 上的活动创建时运行。 工作流程可以使用多个 web 挂钩事件来触发工作流程运行。 For more information, see "Webhooks." For more information about the on syntax, see "Workflow syntax for GitHub 操作."

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

  1. 仓库中发生事件,生成的事件 web 挂钩具有关联的提交 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 引用)环境变量。 更多信息请参阅“使用环境变量”。

注意:无法使用 GITHUB_TOKEN 触发新的工作流程。 更多信息请参阅“使用个人访问令牌触发新的工作流程”。

使用单一事件的示例

# Trigger on push
on: push

使用事件列表的示例

# Trigger the workflow on push or pull request
on: [push, pull_request]

使用具有活动类型或配置的多个事件示例

如果您需要为一个事件指定活动类型或配置,必须分别配置每个事件。 您必须为所有事件附加冒号 (`:</0),包括没有配置的事件。

on:
  # Trigger the workflow on push or pull request,
  # but only for the master branch
  push:
    branches:
      - master
  pull_request:
    branches:
      - master
  # Also trigger on page_build, as well as release created events
  page_build:
  release:
    types: # This configuration does not affect the page_build event above
      - created
`

Web 挂钩事件

您可以将工作流程配置为在 GitHub 上创建 web 挂钩事件时运行。 某些事件有多种触发事件的活动类型。 如果有多种活动类型触发事件,则可以指定哪些活动类型将触发工作流程运行。

检查运行事件:check_run

在发生 check_run 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Check runs."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
check_run- created
- rerequested
- completed
- requested_action


默认分支上的最新提交默认分支

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

例如,您可以在检查运行为 rerequestedrequested_action 时运行工作流程。

on:
  check_run:
    types: [rerequested, requested_action]

检查套件事件:check_suite

在发生 check_suite 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Check suites."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

注意:为防止递归工作流程,如果检查套件是由 GitHub 操作 创建的,则此事件不会触发工作流程。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
check_suite- completed
- requested
- rerequested


默认分支上的最新提交默认分支

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

例如,您可以在检查套件为 rerequestedcompleted 时运行工作流程。

on:
  check_suite:
    types: [rerequested, completed]

创建事件:create

每当有人创建分支或标记(触发 create 事件)时运行您的工作流程。 For information about the REST API, see "Create a reference."

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
createn/a创建的分支或标记上的最新提交创建的分支或标记

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

on:
  create

删除事件:delete

每当有人删除分支或标记(触发 delete 事件)时运行您的工作流程。 For information about the REST API, see "Delete a reference."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Webhook event payload活动类型GITHUB_SHAGITHUB_REF
deleten/a默认分支上的最新提交默认分支

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

on:
  delete

部署事件:deployment

每当有人创建部署(触发 deployment 事件)时运行您的工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。 For information about the REST API, see "Deployments."

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
deploymentn/a要部署的提交要部署的分支或标记(提交时为空)

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

on:
  deployment

部署状态事件:deployment_status

每当第三方提供部署状态(触发 deployment_status 事件)时运行您的工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。 For information about the REST API, see "Create a deployment status."

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
deployment_statusn/a要部署的提交要部署的分支或标记(提交时为空)

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

on:
  deployment_status

复刻事件:fork

每当有人复刻仓库(触发 fork 事件)时运行您的工作流程。 For information about the REST API, see "Create a fork."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
复刻n/a默认分支上的最新提交默认分支

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

on:
  fork

Gollum 事件:gollum

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

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
gollumn/a默认分支上的最新提交默认分支

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

on:
  gollum

议题评论事件:issue_comment

在发生 issue_comment 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Issue comments."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
issue_comment- created
- edited
- deleted


默认分支上的最新提交默认分支

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

例如,您可以在议题评论为 createddeleted 时运行工作流程。

on:
  issue_comment:
    types: [created, deleted]

议题事件:issues

在发生 issues 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Issues."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
issues- opened
- edited
- deleted
- transferred
- pinned
- unpinned
- closed
- reopened
- assigned
- unassigned
- labeled
- unlabeled
- locked
- unlocked
- milestoned
- demilestoned














默认分支上的最新提交默认分支

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

例如,您可以在议题为 openededitedmilestoned 时运行工作流程。

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

标签事件:label

在发生 label 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Labels."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
标签- created
- edited
- deleted


默认分支上的最新提交默认分支

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

例如,您可以在标签为 createddeleted 时运行工作流程。

on:
  label:
    types: [created, deleted]

里程碑事件:milestone

在发生 milestone 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Milestones."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
里程碑- created
- closed
- opened
- edited
- deleted




默认分支上的最新提交默认分支

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

例如,您可以在里程碑为 openeddeleted 时运行工作流程。

on:
  milestone:
    types: [opened, deleted]

页面构建事件:page_build

在有人推送到启用 GitHub Pages 的分支(触发 page_build 事件)的任何时间运行您的工作流程。 For information about the REST API, see "Pages."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
page_buildn/a默认分支上的最新提交n/a

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

on:
  page_build

项目事件:project

在发生 project 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Projects."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
project- created
- updated
- closed
- reopened
- edited
- deleted





默认分支上的最新提交默认分支

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

例如,您可以在项目为 createddeleted 时运行工作流程。

on:
  project:
    types: [created, deleted]

项目卡事件:project_card

在发生 project_card 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Project cards."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
project_card- created
- moved
- converted to an issue
- edited
- deleted



默认分支上的最新提交默认分支

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

例如,您可以在项目卡为 openeddeleted 时运行工作流程。

on:
  project_card:
    types: [opened, deleted]

项目列事件:project_column

在发生 project_column 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Project columns."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
project_column- created
- updated
- moved
- deleted


默认分支上的最新提交默认分支

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

例如,您可以在项目列为 createddeleted 时运行工作流程。

on:
  project_column:
    types: [created, deleted]

公开事件:public

每当有人将私有仓库公开(触发 public 事件)时运行您的工作流程。 For information about the REST API, see "Edit repositories."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
publicn/a默认分支上的最新提交默认分支

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

on:
  public

拉取请求事件:pull_request

在发生 pull_request 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Pull requests."

默认情况下,工作流程仅在 pull_request 的活动类型为 openedsynchronizereopened 时运行。 要让更多活动类型触发工作流程,请使用 types 关键词。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request- assigned
- unassigned
- labeled
- unlabeled
- opened
- edited
- closed
- reopened
- synchronize
- ready_for_review
- locked
- unlocked
- review_requested
- review_request_removed












GITHUB_REF 分支上的最新合并提交PR 合并分支 refs/pull/:prNumber/merge

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

例如,您可以在拉取请求为 assignedopenedsynchronizereopened 时运行工作流程。

on:
  pull_request:
    types: [assigned, opened, synchronize, reopened]
复刻的仓库的拉取请求事件

注:如果从复刻仓库打开拉取请求,工作流程不会在私有基础仓库上运行。

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

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

对复刻的仓库中 GITHUB_TOKEN 的权限为只读。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

拉取请求审查事件:pull_request_review

在发生 pull_request_review 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Pull request reviews."

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request_review- submitted
- edited
- dismissed

GITHUB_REF 分支上的最新合并提交PR 合并分支 refs/pull/:prNumber/merge

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

例如,您可以在拉取请求审查为 editeddismissed 时运行工作流程。

on:
  pull_request_review:
    types: [edited, dismissed]
复刻的仓库的拉取请求事件

注:如果从复刻仓库打开拉取请求,工作流程不会在私有基础仓库上运行。

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

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

对复刻的仓库中 GITHUB_TOKEN 的权限为只读。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

拉取请求审查评论事件:pull_request_review_comment

每当拉取请求统一差异的评论被修改(触发 pull_request_review_comment 事件)时运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see Review comments.

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request_review_comment- created
- edited
- deleted

GITHUB_REF 分支上的最新合并提交PR 合并分支 refs/pull/:prNumber/merge

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

例如,您可以在拉取请求审查评论为 createddeleted 时运行工作流程。

on:
  pull_request_review_comment:
    types: [created, deleted]
复刻的仓库的拉取请求事件

注:如果从复刻仓库打开拉取请求,工作流程不会在私有基础仓库上运行。

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

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

对复刻的仓库中 GITHUB_TOKEN 的权限为只读。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

推送事件:push

注:适用于 GitHub Actions 的 web 挂钩有效负载在 commit 对象中不包括 addedremovedmodified 属性。 您可以使用 REST API 检索完整的提交对象。 For more information, see "Get a single commit"".

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

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
推送n/a推送的提交,除非删除分支(当它是默认分支时)更新的引用

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

on:
  push

注册表包事件: registry_package

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

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
registry_package- published
- updated
Commit of the published package已发布软件包的分支或标签

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

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

on:
  registry_package:
    types: [published]

版本发布事件:release

注意:对草稿发行版不触发 release 事件。

在发生 release 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Releases."

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
发行版- published
- unpublished
- created
- edited
- deleted
- prereleased
- released





标记的发行版中的最新提交发行版标记

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

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

on:
  release:
    types: [published]

状态事件:status

在 Git 提交的状态发生变化(触发 status 事件)的任何时间运行您的工作流程。 For information about the REST API, see Statuses.

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
状态n/a默认分支上的最新提交n/a

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

on:
  status

关注事件:watch

在发生 watch 事件的任何时间运行您的工作流程。 多个活动类型会触发此事件。 For information about the REST API, see "Starring."

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
查看- started默认分支上的最新提交默认分支

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

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

on:
  watch:
    types: [started]

安排的事件:schedule

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
n/an/a默认分支上的最新提交默认分支

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

此示例每隔 15 分钟触发工作流程:

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '*/15 * * * *'

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

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

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

运算符描述示例
*任意值* * * * * 在每天的每分钟运行。
,值列表分隔符2,10 4,5 * * * 在每天第 4 和第 5 小时的第 2 和第 10 分钟运行。
-值的范围0 4-6 * * * 在第 4、5、6 小时的第 0 分钟运行。
/步骤值20/15 * * * * 从第 20 分钟到第 59 分钟每隔 15 分钟运行(第 20、35 和 50 分钟)。

注: GitHub 操作 不支持非标准语法 @yearly@monthly@weekly@daily@hourly@reboot

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

外部事件:repository_dispatch

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
repository_dispatchn/aGITHUB_REF 分支上的最新提交收到了分发的分支

注:仅当工作流程文件在 master 或默认分支上时,此事件才会触发工作流程运行。

当您想要触发在 GitHub 外发生的活动的工作流程时,可以使用 GitHub API 触发名为 repository_dispatch 的 web 挂钩事件。 For more information, see "Create a repository dispatch event."

要触发自定义 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]

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

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

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

问问别人

找不到要找的内容?

联系我们