Skip to main content

触发工作流程的事件

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

关于触发工作流程的事件

工作流程触发器是导致工作流程运行的事件。 有关如何使用工作流程触发器的详细信息,请参阅“触发工作流程”。

可用事件

某些事件具有多种活动类型。 对于这些事件,您可以指定将触发工作流程运行的活动类型。 有关每个活动类型的含义的详细信息,请参阅“web 挂钩事件和有效负载”。 请注意,并非所有 web 挂钩事件都会触发工作流程。

branch_protection_rule

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
branch_protection_rule- created
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在工作流程存储库中的分支保护规则发生更改时运行工作流程。 有关分支保护规则的更多信息,请参阅“关于受保护分支”。 有关分支保护规则 API 的信息,请参阅 GraphQL API 文档中的“BranchProtectionRule”或 REST API 文档中的“分支”。

例如,您可以在分支保护规则为 createddeleted 时运行工作流程。

on:
  branch_protection_rule:
    types: [created, deleted]

check_run

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
check_run- created
- rerequested
- completed
-requested_action
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在发生与检查运行相关的活动时运行工作流程。 检查运行是检查套件中的单个测试。 有关信息,请参阅“检查 API 入门”。 有关检查运行 API 的信息,请参阅 GraphQL API 文档中的“CheckRun”或 REST API 文档中的“检查”。

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

on:
  check_run:
    types: [rerequested, completed]

check_suite

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

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 尽管仅支持 started 活动类型,但如果将来添加更多活动类型,则指定活动类型将使您的工作流程保持特定。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

在发生检查套件活动时运行工作流程。 检查套件是为特定提交创建的检查运行的集合。 检查套件汇总了套件中检查运行的状态和结论。 有关信息,请参阅“检查 API 入门”。 有关检查套件 API 的信息,请参阅 GraphQL API 文档中的“CheckSuite”或 REST API 文档中的“检查”。

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

on:
  check_suite:
    types: [completed]

create

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

注意:一次创建三个以上的标记时,不会创建事件。

当有人在工作流程的存储库中创建 Git 引用(Git 分支或标记)时运行工作流程。 有关用于创建 Git 引用的 API 的信息,请参阅 GraphQL API 文档中的“createRef”或 REST API 文档中的“创建引用”。

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

on:
  create

delete

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

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

注意:一次删除三个以上的标记时,不会创建事件。

当有人删除工作流程存储库中的 Git 引用(Git 分支或标记)时运行工作流程。 有关删除 Git 引用的 API 的信息,请参阅 GraphQL API 文档中的“deleteRef”或 REST API 文档中的“删除引用”。

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

on:
  delete

deployment

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
deploymentn/a要部署的提交要部署的分支或标记(如果使用提交 SHA 创建,则为空)

当有人在工作流程的存储库中创建部署时运行工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。 有关用于创建部署的 API 的信息,请参阅 GraphQL API 文档中的“创建部署”或 REST API 文档中的“部署”。

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

on:
  deployment

deployment_status

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

注意:当部署状态的状态设置为 inactive 时,不会触发工作流程运行。

在第三方提供部署状态时运行工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。 有关用于创建部署状态的 API 的信息,请参阅 GraphQL API 文档中的“createDeploymentStatus”或 REST API 文档中的“创建部署状态”。

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

on:
  deployment_status

讨论

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
讨论- created
- edited
- deleted
- transferred
- pinned
- unpinned
- labeled
- unlabeled
- locked
- unlocked
- category_changed
- answered
- unanswered
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

注意:GitHub Discussions 的 web 挂钩事件目前处于测试阶段,可能会更改。

在创建或修改工作流程存储库中的讨论时运行工作流程。 对于与讨论评论相关的活动,请使用 discussion_comment 事件。 有关讨论的更多信息,请参阅“关于讨论”。 有关 GraphQL API 的信息,请参阅“讨论”。

例如,您可以在讨论为 creatededitedanswered 时运行工作流程。

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

discussion_comment

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
discussion_comment- created
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

注意:GitHub Discussions 的 web 挂钩事件目前处于测试阶段,可能会更改。

在创建或修改工作流程存储库中讨论的评论时运行工作流程。 对于与讨论相关的活动,而不是对讨论的评论,请使用 discussion 事件。 有关讨论的更多信息,请参阅“关于讨论”。 有关 GraphQL API 的信息,请参阅“讨论”。

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

on:
  discussion_comment:
    types: [created, deleted]

复刻

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

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

当有人复刻存储库时运行工作流程。 有关 REST API 的信息,请参阅“创建复刻”。

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

on:
  fork

gollum

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

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

在有人创建或更新 Wiki 页面时运行工作流程。 更多信息请参阅“关于 wiki”。

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

on:
  gollum

issue_comment

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
issue_comment- created
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在创建、编辑或删除议题或拉取请求评论时运行工作流程。 有关议题评论 API 的信息,请参阅 GraphQL API 文档中的“IssueComment”或 REST API 文档中的“议题评论”。

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

on:
  issue_comment:
    types: [created, deleted]

issue_comment 仅用于议题或拉取请求

issue_comment 事件在评论问题和拉取请求时发生。 您可以在条件中使用 github.event.issue.pull_request 属性,根据触发对象是议题还是拉取请求,执行不同的操作。

例如,仅当 issue_comment 事件源自拉取请求时,此工作流程才会运行 pr_commented 作业。 仅当 issue_comment 事件源自某个议题时,它才会运行 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 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 }}

议题

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
议题- opened
- edited
- deleted
- transferred
- pinned
- unpinned
- closed
- reopened
- assigned
- unassigned
- labeled
- unlabeled
- locked
- unlocked
- milestoned
- demilestoned
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在创建或修改工作流程存储库中的议题时运行工作流程。 对于与议题中的评论相关的活动,请使用 issue_comment 事件。 有关议题的更多信息,请参阅“关于议题”。 有关议题 API 的信息,请参阅 GraphQL API 文档中的“Issue”或 REST API 文档中的“议题”。

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

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

标签

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
标签- created
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在创建或修改工作流程存储库中的标签时运行工作流程。 有关标签的更多信息,请参阅“管理标签”。 有关标签 API 的信息,请参阅 GraphQL API 文档中的“标签”或 REST API 文档中的“标签”。

如果要在议题、拉取请求或讨论中添加或删除标签时运行工作流程,请对 issuespull_requestpull_request_targetdiscussion 事件使用 labeledunlabeled 活动类型。

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

on:
  label:
    types: [created, deleted]

里程碑

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
里程碑- created
- closed
- opened
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在创建或修改工作流程存储库中的里程碑时运行工作流程。 有关里程碑的更多信息,请参阅“关于里程碑”。 有关里程碑 API 的信息,请参阅 GraphQL API 文档中的“里程碑”或 REST API 文档中的“里程碑”。

如果要在里程碑中添加或删除议题时运行工作流程,请改为对 issues 事件使用 milestoneddemilestoned 活动类型。

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

on:
  milestone:
    types: [opened, deleted]

page_build

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

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

当有人推送到作为 GitHub Pages 的发布源的分支时,如果为存储库启用了 GitHub Pages ,则运行工作流程。 有关 GitHub Pages 发布源的详细信息,请参阅“为 GitHub Pages 站点配置发布源”。 有关 REST API 的信息,请参阅“页面”。

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

on:
  page_build

project

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
project- created
- closed
- reopened
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 edited 活动类型是指编辑项目板(而不是项目板上的列或卡片)的时间。 有关每种活动类型的详细信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

注意:此事件仅对工作流存储库拥有的项目发生,对于组织拥有或用户拥有的项目,或者对于其他存储库拥有的项目,不会发生此事件。

注意:此事件对项目(测试版)不会发生。 更多信息请参阅“关于项目(测试版)”。

在创建或修改项目板时运行工作流程。 对于与项目板中的卡片或列相关的活动,请改用 project_cardproject_column 事件。 有关项目板的更多信息,请参阅“关于项目板”。 有关项目板 API 的信息,请参阅 GraphQL API 文档中的“项目”或 REST API 文档中的“项目”。

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

on:
  project:
    types: [created, deleted]

project_card

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
project_card- created
- moved
- converted to an issue
- edited
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

注意:此事件仅对工作流存储库拥有的项目发生,对于组织拥有或用户拥有的项目,或者对于其他存储库拥有的项目,不会发生此事件。

注意:此事件对项目(测试版)不会发生。 更多信息请参阅“关于项目(测试版)”。

在创建或修改项目板上的卡片时运行工作流程。 对于与项目板或项目板中的列相关的活动,请改用 projectproject_column 事件。 有关项目板的更多信息,请参阅“关于项目板”。 有关项目卡 API 的信息,请参阅 GraphQL API 文档中的“ProjectCard”或 REST API 文档中的“项目卡”。

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

on:
  project_card:
    types: [created, deleted]

project_column

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
project_column- created
- updated
- moved
- deleted
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

注意:此事件仅对工作流存储库拥有的项目发生,对于组织拥有或用户拥有的项目,或者对于其他存储库拥有的项目,不会发生此事件。

注意:此事件对项目(测试版)不会发生。 更多信息请参阅“关于项目(测试版)”。

在创建或修改项目板上的列时运行工作流程。 对于与项目板或项目板中的卡相关的活动,请改用 projectproject_card 事件。 有关项目板的更多信息,请参阅“关于项目板”。 有关项目列 API 的信息,请参阅 GraphQL API 文档中的“项目列”或 REST API 文档中的“项目列”。

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

on:
  project_column:
    types: [created, deleted]

public

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

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

当工作流程的存储库从私有变为公共时运行工作流程。 有关 REST API 的信息,请参阅“编辑仓库”。

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

on:
  public

pull_request

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request- assigned
- unassigned
- labeled
- unlabeled
- opened
- edited
- closed
- reopened
- synchronize
- converted_to_draft
- ready_for_review
- locked
- unlocked
- review_requested
- review_request_removed
- auto_merge_enabled
- auto_merge_disabled
GITHUB_REF 分支上的最新合并提交PR 合并分支 refs/pull/:prNumber/merge

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,工作流程仅在 pull_request 事件的活动类型为 openedsynchronizereopened 时运行。 要按不同的活动类型触发工作流,请使用 types 关键字。 更多信息请参阅“GitHub Actions 的工作流程语法”。

注意:如果拉取请求具有合并冲突,工作流程将不会在 pull_request 活动上运行。 必须先解决合并冲突。

相反,具有 pull_request_target 事件的工作流程将运行,即使拉取请求存在合并冲突也是如此。 在使用 pull_request_target 触发器之前,您应该了解安全风险。 更多信息请参阅 pull_request_target

在工作流程存储库中发生有关拉取请求的活动时运行工作流程。 例如,如果未指定任何活动类型,则工作流程将在打开或重新打开拉取请求时运行,或者在更新拉取请求的头部分支时运行。 对于与拉取请求审阅、拉取请求审阅评论或拉取请求评论相关的活动,请改用 pull_request_reviewpull_request_review_commentissue_comment 事件。 有关拉取请求 API 的信息,请参阅 GraphQL API 文档中的“PullRequest”或 REST API 文档中的“拉取请求”。

请注意,此事件 GITHUB_SHA 是拉取请求合并分支的最后一个合并提交。 如果要获取最后一次提交到拉取请求的头部分支的提交 ID,请改用 github.event.pull_request.head.sha

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

on:
  pull_request:
    types: [opened, reopened]

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

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'

基于拉取请求的头部分支或基本分支运行工作流程

您可以使用 branchesbranches-ignore 筛选器,将工作流配置为仅针对特定分支的拉取请求运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

注意:If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. 例如,仅当在名称以 releases/开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流程:

on:
  pull_request:
    types:
      - opened
    branches:    
      - 'releases/**'
    paths:
      - '**.js'

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

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/'"

根据拉取请求中更改的文件运行工作流程

您还可以将工作流程配置为在拉取请求更改特定文件时运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

注意:If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. 例如,仅当在名称以 releases/开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流程:

on:
  pull_request:
    types:
      - opened
    branches:    
      - 'releases/**'
    paths:
      - '**.js'

在拉取请求合并时运行工作流程

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

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

复刻的存储库中的工作流程

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

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

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

对于从复刻的存储库到基本存储库的拉取请求,GitHub 将 pull_requestissue_commentpull_request_review_commentpull_request_reviewpull_request_target 事件发送到基本存储库。 复刻的存储库上不会发生任何拉取请求事件。

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

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

注意:由 Dependabot 拉取请求触发的工作流程被视为来自复刻的仓库,也受到这些限制。

pull_request_comment(使用 issue_comment

要在创建、编辑或删除对拉取请求(而不是拉取请求的差异)的评论时运行工作流程,请使用 issue_comment 事件。 对于与拉取请求审核或拉取请求审核评论相关的活动,请使用 pull_request_reviewpull_request_review_comment 事件。

pull_request_review

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request_review- submitted
- edited
- dismissed
GITHUB_REF 分支上的最新合并提交PR 合并分支 refs/pull/:prNumber/merge

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

在提交、编辑或关闭拉取请求审阅时运行工作流程。 拉取请求审查是除正文评论和状态之外的一组拉取请求审查评论。 对于与拉取请求审查评论或拉取请求评论相关的活动,请改用 pull_request_review_commentissue_comment 事件。 有关拉取请求审查 API 的信息,请参阅 GraphQL API 文档中的“PullRequestReview”或 REST API 文档中的“拉取请求审查”。

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

on:
  pull_request_review:
    types: [edited, dismissed]

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

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

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"

复刻的存储库中的工作流程

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

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

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

对于从复刻的存储库到基本存储库的拉取请求,GitHub 将 pull_requestissue_commentpull_request_review_commentpull_request_reviewpull_request_target 事件发送到基本存储库。 复刻的存储库上不会发生任何拉取请求事件。

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

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

注意:由 Dependabot 拉取请求触发的工作流程被视为来自复刻的仓库,也受到这些限制。

pull_request_review_comment

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request_review_comment- created
- edited
- deleted
GITHUB_REF 分支上的最新合并提交PR 合并分支 refs/pull/:prNumber/merge

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

在修改拉取请求审查评论时运行工作流程。 拉取请求审查评论是对拉取请求差异的评论。 对于与拉取请求评论或拉取请求评论相关的活动,请改用 pull_request_reviewissue_comment 事件。 有关拉取请求审查评论 API 的信息,请参阅 GraphQL API 文档中的“PullRequestReviewComment”或 REST API 文档中的“审查评论”。

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

on:
  pull_request_review_comment:
    types: [created, deleted]

复刻的存储库中的工作流程

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

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

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

对于从复刻的存储库到基本存储库的拉取请求,GitHub 将 pull_requestissue_commentpull_request_review_commentpull_request_reviewpull_request_target 事件发送到基本存储库。 复刻的存储库上不会发生任何拉取请求事件。

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

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

注意:由 Dependabot 拉取请求触发的工作流程被视为来自复刻的仓库,也受到这些限制。

pull_request_target

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
pull_request- assigned
- unassigned
- labeled
- unlabeled
- opened
- edited
- closed
- reopened
- synchronize
- converted_to_draft
- ready_for_review
- locked
- unlocked
- review_requested
- review_request_removed
- auto_merge_enabled
- auto_merge_disabled
PR 基分支上的最后一次提交PR 基础分支

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,工作流程仅在 pull_request_target 活动的类型为 openedsynchronizereopened 时运行。 要按不同的活动类型触发工作流,请使用 types 关键字。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

警告: 对于由 pull_request_target 事件触发的工作流程,除非指定了 permissions 密钥并且工作流程可以访问机密,否则将向 GITHUB_TOKEN 授予读/写存储库权限, 即使它是从复刻触发的。 虽然工作流程在拉取请求的基础上下文中运行,但您应该确保不在此事件中检出、生成或运行来自拉取请求的不受信任代码。 此外,任何缓存都与基本分支共享相同的作用域。 为帮助防止缓存中毒,如果缓存内容可能已更改,则不应保存缓存。 更多信息请参阅 GitHub 安全实验室网站上的“保持 GitHub Actions 和工作流程安全:阻止 pwn 请求”。

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

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

基于拉取请求的头部分支或基本分支运行工作流程

您可以使用 branchesbranches-ignore 筛选器,将工作流配置为仅针对特定分支的拉取请求运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

注意:If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. 例如,仅当在名称以 releases/开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流程:

on:
  pull_request_target:
    types:
      - opened
    branches:    
      - 'releases/**'
    paths:
      - '**.js'

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

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/'"

根据拉取请求中更改的文件运行工作流程

您可以使用 pathspaths-ignore 筛选器来配置工作流程,以便在拉取请求更改特定文件时运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

注意:If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. 例如,仅当在名称以 releases/开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流程:

on:
  pull_request_target:
    types:
      - opened
    branches:    
      - 'releases/**'
    paths:
      - '**.js'

在拉取请求合并时运行工作流程

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

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

推送

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

注:适用于 GitHub Actions 的 web 挂钩有效负载在 commit 对象中不包括 addedremovedmodified 属性。 您可以使用 API 检索完整的提交对象。 有关信息,请参阅 GraphQL API 文档中的“提交”或 REST API 文档中的“获取提交”。

注意:一次推送三个以上的标记时,不会创建事件。

在推送提交或标记时运行工作流程。

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

on:
  push

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

您可以使用 branchesbranches-ignore 筛选器,将工作流程配置为仅在推送特定分支时运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

注意:If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. 例如,仅当向名称以 releases/开头的分支发出包含 JavaScript (.js) 文件更改的推送时,才会运行以下工作流程:

on:
  push:
    branches:    
      - 'releases/**'
    paths:
      - '**.js'

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

您可以使用 tagstags-ignore 筛选器,将工作流程配置为仅在特定标记或推送时运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

on:
  push:
    tags:        
      - v1.**

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

可以使用 pathspaths-ignore 筛选器配置工作流程在推送到特定文件时运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

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

注意:If you use both the branches filter and the paths filter, the workflow will only run when both filters are satisfied. 例如,仅当向名称以 releases/开头的分支发出包含 JavaScript (.js) 文件更改的推送时,才会运行以下工作流程:

on:
  push:
    branches:    
      - 'releases/**'
    paths:
      - '**.js'

registry_package

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

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

当存储库中发生与 GitHub Packages 相关的活动时运行工作流程。 更多信息请参阅“GitHub Packages 文档”。

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

on:
  registry_package:
    types: [published]

发行版

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
发行版- published
- unpublished
- created
- edited
- deleted
- prereleased
- released
标记的发行版中的最新提交发行版 refs/tags/<tag_name> 的标记引用

注意:多个活动类型会触发此事件。 有关每种活动类型的信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

注意:对于草稿发行版的 createdediteddeleted 活动类型,不会触发工作流程。 当您通过 GitHub 浏览器 UI 创建版本时,您的版本可能会自动另存为草稿。

注意:prereleased 类型不会触发从草稿版本预发布,但 published 类型会触发。 如果您希望工作流程在稳定预发布时运行,请订阅 published 而不是 releasedprereleased

在存储库中发生发布活动时运行工作流程。 有关发行版 API 的信息,请参阅 GraphQL API 文档中的“发行版”或 REST API 文档中的“发行版”。

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

on:
  release:
    types: [published]

repository_dispatch

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
repository_dispatch自定义默认分支上的最新提交默认分支

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

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

当您请求创建 repository_dispatch 事件时,必须指定 event_type 以描述活动类型。 默认情况下,所有 repository_dispatch 活动类型都会触发工作流程运行。 您可以使用 types 关键字来限制工作流程在 repository_dispatch web 挂钩负载中发送特定 event_type 值时运行。

on:
  repository_dispatch:
    types: [on-demand-test]

注意: event_type 值限制为 100 个字符。

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

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

则您可以在如下工作流程中访问有效负载:

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

计划

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

注意: schedule 事件在 GitHub Actions 工作流程运行期间负载过高时可能会延迟。 高负载时间包括每小时的开始时间。 为了降低延迟的可能性,将您的工作流程安排在不同时间运行。

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 * * *'

单个工作流程可由多个计划事件触发。 您可以通过 github.event.schedule 上下文访问触发工作流程的计划事件。 本示例触发工作流在每周一至周四的 5:30 UTC 运行,但在星期一和星期三跳过星期一或星期三不运行步骤。

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 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"

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

┌───────────── 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 分钟)。

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

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

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

状态

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

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

在 Git 提交状态更改时运行工作流程。 例如,提交可标记为 errorfailurependingsuccess。 如果要提供有关状态更改的更多详细信息,则可能需要使用 check_run 事件。 有关提交状态 API 的信息,请参阅 GraphQL API 文档中的“状态”或 REST API 文档中的“状态”。

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

on:
  status

如果要基于新的提交状态在工作流程中运行作业,可以使用 github.event.state 上下文。 例如,以下工作流程在提交状态更改时触发,但仅当新的提交状态为 errorfailure 时, if_error_or_failure 作业才会运行。

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

查看

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

注意:多个活动类型会触发此事件。尽管仅支持 started 活动类型,但如果将来添加更多活动类型,则指定活动类型将使您的工作流程保持特定。 有关每种活动类型的详细信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

在工作流程的存储库加星标时运行工作流程。 有关拉取请求 API 的信息,请参阅 GraphQL API 文档中的“addStar”或 REST API 文档中的“标星”。

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

on:
  watch:
    types: [started]

workflow_call

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
与调用方工作流程相同n/a与调用方工作流程相同与调用方工作流程相同

workflow_call 用于指示一个工作流程可以由另一个工作流程调用。 当使用 workflow_call 事件触发工作流程时,被调用工作流程中的事件负载与调用工作流程中的事件负载相同。 更多信息请参阅“重用工作流程”。

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

on: workflow_call

workflow_dispatch

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

要手动触发工作流程,请使用 workflow_dispatch 事件。 您可以使用 GitHub API、GitHub CLI或 GitHub 浏览器界面手动触发工作流程运行。 更多信息请参阅“手动配置工作流程

on: workflow_dispatch

提供输入

您可以直接在工作流程中配置事件的自定义输入属性、默认输入值和必要输入。 触发事件时,可以提供 ref 和任何 inputs。 在工作流程运行时,您可以访问 inputs 上下文中的输入值。 更多信息请参阅“上下文”。

Note: The workflow will also receive the inputs in the github.event.inputs context. The information in the inputs context and github.event.inputs context is identical except that the inputs context preserves Boolean values as Booleans instead of converting them to strings.

此示例定义了称为 logLeveltagsenvironment 的输入。 在运行工作流程时,可以将这些输入的值传递给工作流程。 然后,此工作流程使用 inputs.logLevelinputs.tagsinputs.environment 上下文属性,将值打印到日志中。

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 }}

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

输入工作流程的输入

还可以在从脚本运行工作流程时传递输入,或者使用 GitHub CLI。 例如:

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

更多信息请参阅“手动运行工作流程”中的 GitHub CLI 信息。

workflow_run

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

注意:多个活动类型会触发此事件。 重新运行工作流程时,不会发生 requested 活动类型。 有关每种活动类型的详细信息,请参阅“web 挂钩事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流程。 您可以使用 types(类型) 关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。

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

注意: 不能使用 workflow_run 将超过三级的工作流程链接在一起。 例如,如果尝试触发五个工作流程(名称为 BF)在初始工作流程 A 运行后按顺序运行(即:ABCDEF),则工作流程 EF 不会运行。

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

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

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

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

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

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

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

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'

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

您可以使用 branchesbranches-ignore 筛选器来指定触发工作流程必须在哪些分支上运行才能触发您的工作流程。 更多信息请参阅“GitHub Actions 的工作流程语法”。 例如,仅当名为 Build 的工作流程在名为 <0>Canary 的分支上运行时,具有以下触发器的工作流程才会运行。

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

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

您可以访问与触发工作流程的工作流程对应的 workflow_run 事件有效负载。 例如,如果触发工作流程生成构件,则使用 workflow_run 事件触发的工作流程可以访问这些构件。

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

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@v3
        with:
          name: pr_number
          path: pr/

当上述工作流程的运行完成时,它将触发以下工作流程的运行。 以下工作流程使用 github.event.workflow_run 上下文和 GitHub REST API 下载由上述工作流程上传的构件,解压缩下载的构件,并对其编号作为构件上传的拉取请求进行评论。

name: Use the data

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

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - name: 'Download artifact'
        uses: actions/github-script@v6
        with:
          script: |
            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
               owner: context.repo.owner,
               repo: context.repo.repo,
               run_id: context.payload.workflow_run.id,
            });
            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
              return artifact.name == "pr_number"
            })[0];
            let download = await github.rest.actions.downloadArtifact({
               owner: context.repo.owner,
               repo: context.repo.repo,
               artifact_id: matchArtifact.id,
               archive_format: 'zip',
            });
            let fs = require('fs');
            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/pr_number.zip`, Buffer.from(download.data));

      - name: 'Unzip artifact'
        run: unzip pr_number.zip

      - name: 'Comment on PR'
        uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            let fs = require('fs');
            let issue_number = Number(fs.readFileSync('./pr_number'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: issue_number,
              body: 'Thank you for the PR!'
            });