Skip to main content

触发工作流的事件

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

关于触发工作流程的事件

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

某些事件具有多种活动类型。 对于这些事件,你可以指定将触发工作流程运行的活动类型。 有关每个活动类型的含义的详细信息,请参阅“Webhook 事件和有效负载”。

注意:并非所有 Webhook 事件都触发工作流。

branch_protection_rule

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

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

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

在工作流程存储库中的分支保护规则发生更改时运行工作流程。 有关分支保护规则的详细信息,请参阅“关于受保护分支”。 有关分支保护规则 API 的信息,请参阅 GraphQL API 文档中的“对象”或“分支的 REST API 终结点及其设置”。

例如,可以在分支保护规则状态为 createddeleted 时运行工作流:

on:
  branch_protection_rule:
    types: [created, deleted]

check_run

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

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

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

在发生与检查运行相关的活动时运行工作流程。 检查运行是检查套件中的单个测试。 如需相关信息,请参阅“使用 REST API 与检查交互”。 有关检查运行 API 的信息,请参阅 GraphQL API 文档中的“对象”或“检查运行的 REST API 终结点”。

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

on:
  check_run:
    types: [rerequested, completed]

check_suite

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

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

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

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

在发生检查套件活动时运行工作流程。 检查套件是为特定提交创建的检查运行的集合。 检查套件汇总了套件中检查运行的状态和结论。 如需相关信息,请参阅“使用 REST API 与检查交互”。 有关检查套件 API 的信息,请参阅 GraphQL API 文档中的“对象”或“检查套件的 REST API 终结点”。

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

on:
  check_suite:
    types: [completed]

create

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
create不适用创建的分支或标记上的最新提交创建的分支或标记

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

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

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

on:
  create

delete

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
delete不适用默认分支上的最新提交默认分支

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

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

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

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

on:
  delete

deployment

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

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

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

on:
  deployment

deployment_status

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

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

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

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

on:
  deployment_status

discussion

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

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

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

注意: GitHub Discussions 的 Webhook 事件目前为 beta 版本,可能会有变动。

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

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

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

discussion_comment

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

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

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

注意: GitHub Discussions 的 Webhook 事件目前为 beta 版本,可能会有变动。

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

例如,可以在讨论评论的状态为 createddeleted 时运行工作流。

on:
  discussion_comment:
    types: [created, deleted]

fork

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
fork不适用默认分支上的最新提交默认分支

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

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

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

on:
  fork

gollum

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
gollum不适用默认分支上的最新提交默认分支

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

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

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

on:
  gollum

issue_comment

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

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

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

在创建、编辑或删除议题或拉取请求评论时运行工作流程。 有关问题注释 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Webhook 事件和有效负载”。

例如,可以在问题或拉取请求注释的状态为 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 }}

issues

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

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

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

在创建或修改工作流程存储库中的议题时运行工作流程。 对于与问题中的注释相关的活动,请使用 issue_comment 事件。 有关问题的详细信息,请参阅“关于议题”。 有关问题 API 的信息,请参阅 GraphQL API 文档中的“对象”或“适用于问题的 REST API 终结点”。

例如,可以在问题状态为 openededitedmilestoned 时运行工作流。

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

label

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

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

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

在创建或修改工作流程存储库中的标签时运行工作流程。 有关标签的详细信息,请参阅“管理标签”。 有关标签 API 的信息,请参阅 GraphQL API 文档中的“对象”或“适用于标签的 REST API 终结点”。

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

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

on:
  label:
    types: [created, deleted]

merge_group

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
merge_groupchecks_requested合并组的 SHA合并组的引用

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

将拉取请求添加到合并队列时运行工作流,将拉取请求添加到合并组。 有关详细信息,请参阅“将拉取请求与合并队列合并”。

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

on:
  merge_group:
    types: [checks_requested]

milestone

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

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

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

在创建或修改工作流程存储库中的里程碑时运行工作流程。 有关里程碑的详细信息,请参阅“关于里程碑”。 有关检查里程碑 API 的信息,请参阅 GraphQL API 文档中的“对象”或“适用于里程碑的 REST API 终结点”。

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

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

on:
  milestone:
    types: [opened, deleted]

page_build

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
page_build不适用默认分支上的最新提交不适用

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

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

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

on:
  page_build

project

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

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

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

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

注意:此事件仅适用于 projects (classic)。

在创建或修改 项目(经典) 时运行工作流程。 对于与 项目(经典) 中的卡片或列相关的活动,请改用 project_cardproject_column 事件。 有关 项目(经典) 的详细信息,请参阅“关于 projects (classic)”。 有关 项目(经典) API 的信息,请参阅 GraphQL API 文档中的“对象”或“Projects (classic) 的 REST API 终结点”。

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

on:
  project:
    types: [created, deleted]

project_card

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

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

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

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

注意:此事件仅适用于 projects (classic)。

在创建或修改 项目(经典) 上的卡片时运行工作流程。 对于与 项目(经典) 中的 项目(经典) 或列相关的活动,请改用 projectproject_column 事件。 有关 项目(经典) 的详细信息,请参阅“关于 projects (classic)”。 有关项目卡 API 的信息,请参阅 GraphQL API 文档中的“对象”或“Project (classic) 卡的 REST API 终结点”。

例如,可以在项目卡片的状态为 createddeleted 时运行工作流。

on:
  project_card:
    types: [created, deleted]

project_column

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

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

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

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

注意:此事件仅适用于 projects (classic)。

在创建或修改 项目(经典) 上的列时运行工作流程。 对于与 项目(经典) 中的 项目(经典) 或卡片相关的活动,请改用 projectproject_card 事件。 有关 项目(经典) 的详细信息,请参阅“关于 projects (classic)”。 有关项目列 API 的信息,请参阅 GraphQL API 文档中的“对象”或“Projects (classic) 的 REST API 终结点”。

例如,可以在项目列的状态为 createddeleted 时运行工作流。

on:
  project_column:
    types: [created, deleted]

public

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
public不适用默认分支上的最新提交默认分支

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

当工作流程的存储库从私有变为公共时运行工作流程。 有关 REST API 的信息,请参阅“存储库的 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
- locked
- unlocked
- enqueued
- dequeued
- milestoned
- demilestoned
- ready_for_review
- review_requested
- review_request_removed
- auto_merge_enabled
- auto_merge_disabled
GITHUB_REF 分支上的最后一次合并提交PR 合并分支 refs/pull/PULL_REQUEST_NUMBER/merge

注意:

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

  • 如果拉取请求存在合并冲突,工作流将不会在 pull_request 活动上运行。 必须先解决合并冲突。

    相反,具有 pull_request_target 事件的工作流将运行,即使拉取请求存在合并冲突也是如此。 在使用 pull_request_target 触发器之前,应注意安全风险。 有关详细信息,请参阅 pull_request_target

  • 对于合并的拉取请求和来自分支存储库的拉取请求,pull_request Webhook 事件负载为空。

  • 已关闭的拉取请求的 GITHUB_REF 值会根据该拉取请求是否已被合并而有所不同。 如果拉取请求已关闭但未合并,则值为 refs/pull/PULL_REQUEST_NUMBER/merge。 如果拉取请求因被合并而关闭,则它将是合并到的分支的完全限定 ref,例如 /refs/heads/main

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

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

可以使用 branchesbranches-ignore 筛选器配置工作流,使其仅在面向特定分支的拉取请求上运行。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

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

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

注意:如果同时使用 branches 筛选器和 paths 筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅当在名称以 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/'"

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

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

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

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

注意:如果同时使用 branches 筛选器和 paths 筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅当在名称以 releases/ 开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流:

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

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

当拉取请求合并时,拉取请求将自动关闭。 要在拉取请求合并时运行工作流,请使用 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

存储库分支中的工作流

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

GITHUB_TOKEN 外,当从分支存储库触发工作流时,机密不会传递给运行器。 GITHUB_TOKEN 在存储库分支的拉取请求中具有只读权限。 有关详细信息,请参阅“自动令牌身份验证”。

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

对于从存储库分支到基础存储库的拉取请求,GitHub Enterprise Cloud 会将 pull_requestissue_commentpull_request_review_commentpull_request_reviewpull_request_target 事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时,拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息,请参阅“批准复刻中的工作流程运行”。

对于从分支存储库到专用存储库的拉取请求,工作流仅在启用时运行,请参阅“管理存储库的 GitHub Actions 设置”。

注意: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/PULL_REQUEST_NUMBER/merge

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

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

存储库分支中的工作流

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

GITHUB_TOKEN 外,当从分支存储库触发工作流时,机密不会传递给运行器。 GITHUB_TOKEN 在存储库分支的拉取请求中具有只读权限。 有关详细信息,请参阅“自动令牌身份验证”。

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

对于从存储库分支到基础存储库的拉取请求,GitHub Enterprise Cloud 会将 pull_requestissue_commentpull_request_review_commentpull_request_reviewpull_request_target 事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时,拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息,请参阅“批准复刻中的工作流程运行”。

对于从分支存储库到专用存储库的拉取请求,工作流仅在启用时运行,请参阅“管理存储库的 GitHub Actions 设置”。

注意:Dependabot 拉取请求触发的工作流被视为来自存储库分支,也受到这些限制。

pull_request_review_comment

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

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

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

例如,可以在拉取请求审查注释的状态为 createddeleted 时运行工作流。

on:
  pull_request_review_comment:
    types: [created, deleted]

存储库分支中的工作流

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

GITHUB_TOKEN 外,当从分支存储库触发工作流时,机密不会传递给运行器。 GITHUB_TOKEN 在存储库分支的拉取请求中具有只读权限。 有关详细信息,请参阅“自动令牌身份验证”。

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

对于从存储库分支到基础存储库的拉取请求,GitHub Enterprise Cloud 会将 pull_requestissue_commentpull_request_review_commentpull_request_reviewpull_request_target 事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。

当参与者第一次向公共存储库提交拉取请求时,拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息,请参阅“批准复刻中的工作流程运行”。

对于从分支存储库到专用存储库的拉取请求,工作流仅在启用时运行,请参阅“管理存储库的 GitHub Actions 设置”。

注意: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 基础分支

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

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

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

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

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

例如,可以在拉取请求的状态为 assignedopenedsynchronizereopened 时运行工作流。

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

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

可以使用 branchesbranches-ignore 筛选器配置工作流,使其仅在面向特定分支的拉取请求上运行。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

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

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

注意:如果同时使用 branches 筛选器和 paths 筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅当在名称以 releases/ 开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流:

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

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

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 工作流

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

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

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

注意:如果同时使用 branches 筛选器和 paths 筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅当在名称以 releases/ 开头的分支上打开包含 JavaScript (.js) 文件更改的拉取请求时,才会运行以下工作流:

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

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

当拉取请求合并时,拉取请求将自动关闭。 要在拉取请求合并时运行工作流,请使用 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

push

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
push不适用删除分支时,工作流运行中的 SHA(及其关联的 refs)将恢复为存储库的默认分支。更新的引用

注意:可用于 GitHub Actions 的 Webhook 有效负载不包括 commit 对象中的 addedremovedmodified 属性。 你可以使用 API 检索完整的提交对象。 有关详细信息,请参阅 GraphQL API 文档中的“对象”或“适用于提交的 REST API 终结点”。

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

在推送提交或标记或使用模板创建存储库时运行工作流。

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

on:
  push

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

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

可以使用 branchesbranches-ignore 筛选器配置工作流,使其仅在推送特定分支时运行。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。

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

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

注意:如果同时使用 branches 筛选器和 paths 筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅在将包含 JavaScript (.js) 文件更改的推送发送到名称以 releases/ 开头的分支时,以下工作流才会运行:

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'

注意:如果同时使用 branches 筛选器和 paths 筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅在将包含 JavaScript (.js) 文件更改的推送发送到名称以 releases/ 开头的分支时,以下工作流才会运行:

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

registry_package

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

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

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

注意:推送多体系结构容器映像时,此事件在每个清单中发生一次,因此你可能会观察到工作流触发多次。 若要缓解此问题,并且仅为包含实际图像标记信息的事件运行工作流作业,请使用条件:

jobs:
    job_name:
        if: ${{ github.event.registry_package.package_version.container_metadata.tag.name != '' }}

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

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

on:
  registry_package:
    types: [published]

release

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

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

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

注意:对于从草稿版本发布的预发行版本,prereleased 类型不会触发工作流,但 published 类型会触发。 如果想要在稳定版和预发行版发布时运行工作流,请订阅 published 而不是 releasedprereleased

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

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

on:
  release:
    types: [published]

repository_dispatch

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

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

若想要触发 GitHub Enterprise Cloud 外部发生的活动的工作流,可以使用 GitHub Enterprise Cloud API 触发名为 repository_dispatch 的 Webhook 事件。 有关详细信息,请参阅“存储库的 REST API 终结点”。

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

on:
  repository_dispatch:
    types: [test_result]

注意: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

注释

  • client_payload 中顶级属性的最大数目为 10。
  • 有效负载最多可包含 65,535 个字符。

schedule

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

注意:

  • schedule 事件在 GitHub Actions 工作流运行期间负载过高时可能会延迟。 高负载时间包括每小时的开始时间。 如果负载足够高,可能会删除一些排队作业。 为了降低延迟的可能性,将您的工作流程安排在不同时间运行。
  • 在公共仓库中,当 60 天内未发生仓库活动时,将自动禁用计划的工作流程。 有关重新启用已被禁用的工作流的信息,请参阅“禁用和启用工作流”。
  • 从组织中删除最后一个提交到计划工作流的用户后,该计划工作流将被禁用。 如果具有存储库 write 权限的用户提交到计划工作流文件,则该计划工作流将重新激活。

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

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

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 帮助生成 cron 语法并确认其运行时间。 为了帮助入门,我们还提供了 crontab guru 示例列表。

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

status

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
status不适用默认分支上的最新提交不适用

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

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

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

on:
  status

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

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_SHAGITHUB_REF
watch- started默认分支上的最新提交默认分支

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

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

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

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

on:
  watch:
    types: [started]

workflow_call

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

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

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

on: workflow_call

workflow_dispatch

Web 挂钩事件有效负载活动类型GITHUB_SHAGITHUB_REF
workflow_dispatch不适用GITHUB_REF 分支或标记上的最后一次提交收到调度的分支或标记

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

若要启用手动触发工作流,需要配置 workflow_dispatch 事件。 你可以使用 GitHub Enterprise Cloud API、GitHub CLI或 GitHub Enterprise Cloud 浏览器界面手动触发工作流程运行。 有关详细信息,请参阅“手动运行工作流程”。

on: workflow_dispatch

提供输入

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

注释

  • 工作流还将接收 github.event.inputs 上下文中的输入。 inputs 上下文和 github.event.inputs 上下文中的信息完全相同,但 inputs 上下文将布尔值保留为布尔值,而不是将它们转换为字符串。 choice 类型解析为字符串,是单个可选选项。
  • inputs 的顶级属性的最大数目为 10。
  • inputs 的最大有效负载为 65,535 个字符。

此示例定义了名为 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
- in_progress
默认分支上的最新提交默认分支

注意:多个活动类型会触发此事件。 重新运行工作流时不会出现 requested 活动类型。 有关每种活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 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 的工作流在名为 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@v4
        with:
          name: pr_number
          path: pr/

当上述工作流程的运行完成时,它将触发以下工作流程的运行。 以下工作流使用 github.event.workflow_run 上下文和 GitHub Enterprise Cloud 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!'
            });