关于触发工作流程的事件
工作流程触发器是导致工作流程运行的事件。 有关如何使用工作流触发器的详细信息,请参阅“触发工作流程”。
某些事件具有多种活动类型。 对于这些事件,您可以指定将触发工作流程运行的活动类型。 有关每个活动类型的含义的详细信息,请参阅“Webhook 事件和有效负载”。
注意:并非所有 Webhook 事件都触发工作流。
branch_protection_rule
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
branch_protection_rule | - created - edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在工作流程存储库中的分支保护规则发生更改时运行工作流程。 有关分支保护规则的详细信息,请参阅“关于受保护分支”。 有关分支保护规则 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“分支”。
例如,可以在分支保护规则状态为 created
或 deleted
时运行工作流:
on:
branch_protection_rule:
types: [created, deleted]
check_run
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
check_run | - created - rerequested - completed - requested_action | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在发生与检查运行相关的活动时运行工作流程。 检查运行是检查套件中的单个测试。 如需相关信息,请参阅“使用 REST API 与检查交互”。 有关检查运行 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“检查”。
例如,可以在检查运行状态为 rerequested
或 completed
时运行工作流。
on:
check_run:
types: [rerequested, completed]
check_suite
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_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_SHA | GITHUB_REF |
---|---|---|---|
create | 不适用 | 创建的分支或标记上的最新提交 | 创建的分支或标记 |
注意:一次创建三个以上的标记时,不会创建事件。
当有人在工作流程的存储库中创建 Git 引用(Git 分支或标记)时运行工作流程。 有关用于创建 Git 引用的 API 的信息,请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“Git 数据库”。
例如,可以在发生 create
事件时运行工作流。
on:
create
delete
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
delete | 不适用 | 默认分支上的最新提交 | 默认分支 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
注意:一次删除三个以上的标记时,不会创建事件。
当有人删除工作流程存储库中的 Git 引用(Git 分支或标记)时运行工作流程。 有关用于删除 Git 引用的 API 的信息,请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“Git 数据库”。
例如,可以在发生 delete
事件时运行工作流。
on:
delete
deployment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
deployment | 不适用 | 要部署的提交 | 要部署的分支或标记(如果使用提交 SHA 创建,则为空) |
当有人在工作流程的存储库中创建部署时运行工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。有关用于创建部署的 API 的信息,请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“存储库”。
例如,可以在发生 deployment
事件时运行工作流。
on:
deployment
deployment_status
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
deployment_status | 不适用 | 要部署的提交 | 要部署的分支或标记(提交时为空) |
注意:将部署状态设置为 inactive
时,不会触发工作流运行。
在第三方提供部署状态时运行工作流程。 使用提交 SHA 创建的部署可能没有 Git 引用。有关用于创建部署状态的 API 的信息,请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“部署”。
例如,可以在发生 deployment_status
事件时运行工作流。
on:
deployment_status
discussion
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_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 的信息,请参阅“对象”。
例如,可以在讨论状态为 created
、edited
或 answered
时运行工作流。
on:
discussion:
types: [created, edited, answered]
discussion_comment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
discussion_comment | - created - edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
注意: GitHub Discussions 的 Webhook 事件目前为 beta 版本,可能会有变动。
在创建或修改工作流程存储库中讨论的评论时运行工作流程。 对于与讨论(而非讨论的评论)相关的活动,请使用 discussion
事件。 有关讨论的详细信息,请参阅“关于讨论”。 有关 GraphQL API 的信息,请参阅“对象”。
例如,可以在讨论评论的状态为 created
或 deleted
时运行工作流。
on:
discussion_comment:
types: [created, deleted]
fork
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
fork | 不适用 | 默认分支上的最新提交 | 默认分支 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
当有人复刻存储库时运行工作流程。 有关 REST API 的信息,请参阅“存储库”。
例如,可以在发生 fork
事件时运行工作流。
on:
fork
gollum
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
gollum | 不适用 | 默认分支上的最新提交 | 默认分支 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在有人创建或更新 Wiki 页面时运行工作流程。 有关详细信息,请参阅“关于 wikis”。
例如,可以在发生 gollum
事件时运行工作流。
on:
gollum
issue_comment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
issue_comment | - created - edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在创建、编辑或删除议题或拉取请求评论时运行工作流程。 有关问题注释 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Webhook 事件和有效负载”。
例如,可以在问题或拉取请求注释的状态为 created
或 deleted
时运行工作流。
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_SHA | GITHUB_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 文档中的“问题”。
例如,可以在问题状态为 opened
、edited
或 milestoned
时运行工作流。
on:
issues:
types: [opened, edited, milestoned]
label
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
label | - created - edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在创建或修改工作流程存储库中的标签时运行工作流程。 有关标签的详细信息,请参阅“管理标签”。 有关标签 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“问题”。
如果要在问题、拉取请求或讨论中添加或删除标签时运行工作流,请针对 issues
、pull_request
、pull_request_target
或 discussion
事件改用 labeled
或 unlabeled
活动类型。
例如,可以在标签状态为 created
或 deleted
时运行工作流。
on:
label:
types: [created, deleted]
merge_group
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
merge_group | checks_requested | 合并组的 SHA | 合并组的引用 |
注意:多个活动类型会触发此事件。 尽管仅支持 checks_requested
活动类型,但如果将来添加更多活动类型,则指定活动类型将使工作流保持特定。 有关每种活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
将拉取请求添加到合并队列时运行工作流,将拉取请求添加到合并组。 有关详细信息,请参阅“将拉取请求与合并队列合并”。
例如,可以在发生 checks_requested
活动时运行工作流。
on:
merge_group:
types: [checks_requested]
milestone
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
milestone | - created - closed - opened - edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在创建或修改工作流程存储库中的里程碑时运行工作流程。 有关里程碑的详细信息,请参阅“关于里程碑”。 有关里程碑 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“问题”。
若想要在将问题添加到里程碑或从里程碑中删除问题时运行工作流,请针对 issues
事件改用 milestoned
或 demilestoned
活动类型。
例如,可以在里程碑状态为 opened
或 deleted
时运行工作流。
on:
milestone:
types: [opened, deleted]
page_build
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
page_build | 不适用 | 默认分支上的最新提交 | 不适用 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
当有人推送到作为 GitHub Pages 的发布源的分支时,如果为存储库启用了 GitHub Pages ,则运行工作流程。 有关 GitHub Pages 发布源的详细信息,请参阅“配置 GitHub Pages 站点的发布源”。 有关 REST API 的信息,请参阅“存储库”。
例如,可以在发生 page_build
事件时运行工作流。
on:
page_build
project
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
project | - created - closed - reopened - edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 edited
活动类型是指编辑项目板(而不是项目板上的列或卡片)。 有关每种活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
注意:此事件仅对工作流存储库拥有的项目发生,对于组织拥有或用户拥有的项目,或者对于其他存储库拥有的项目,不会发生此事件。
注意:此事件仅适用于 projects (classic)。
在创建或修改项目板时运行工作流程。 对于与项目板中的卡片或列相关的活动,请改用 project_card
或 project_column
事件。 有关项目版块的详细信息,请参阅“关于 projects (classic)”。 有关项目版块 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Projects (classic)”。
例如,可以在项目状态为 created
或 deleted
时运行工作流。
on:
project:
types: [created, deleted]
project_card
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
project_card | - created - moved - converted 到问题- edited - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
注意:此事件仅对工作流存储库拥有的项目发生,对于组织拥有或用户拥有的项目,或者对于其他存储库拥有的项目,不会发生此事件。
注意:此事件仅适用于 projects (classic)。
在创建或修改项目板上的卡片时运行工作流程。 对于与项目板或项目板中的列相关的活动,请改用 project
或 project_column
事件。 有关项目版块的详细信息,请参阅“关于 projects (classic)”。 有关项目卡 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Projects (classic)”。
例如,可以在项目卡片的状态为 created
或 deleted
时运行工作流。
on:
project_card:
types: [created, deleted]
project_column
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
project_column | - created - updated - moved - deleted | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
注意:此事件仅对工作流存储库拥有的项目发生,对于组织拥有或用户拥有的项目,或者对于其他存储库拥有的项目,不会发生此事件。
注意:此事件仅适用于 projects (classic)。
在创建或修改项目板上的列时运行工作流程。 对于与项目板或项目板中的卡片相关的活动,请改用 project
或 project_card
事件。 有关项目版块的详细信息,请参阅“关于 projects (classic)”。 有关项目列 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“Projects (classic)”。
例如,可以在项目列的状态为 created
或 deleted
时运行工作流。
on:
project_column:
types: [created, deleted]
public
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
public | 不适用 | 默认分支上的最新提交 | 默认分支 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
当工作流程的存储库从私有变为公共时运行工作流程。 有关 REST API 的信息,请参阅“存储库”。
例如,可以在发生 public
事件时运行工作流。
on:
public
pull_request
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_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 |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,工作流仅在 pull_request
事件的活动类型为 opened
、synchronize
或 reopened
时运行。 要按不同的活动类型触发工作流,请使用 types
关键字。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:如果拉取请求存在合并冲突,工作流将不会在 pull_request
活动上运行。 必须先解决合并冲突。
相反,具有 pull_request_target
事件的工作流将运行,即使拉取请求存在合并冲突也是如此。 在使用 pull_request_target
触发器之前,应注意安全风险。 有关详细信息,请参阅 pull_request_target
。
在工作流程存储库中发生有关拉取请求的活动时运行工作流程。 例如,如果未指定任何活动类型,则工作流程将在打开或重新打开拉取请求时运行,或者在更新拉取请求的头部分支时运行。 对于与拉取请求审查、拉取请求审查注释或拉取请求注释相关的活动,请改用 pull_request_review
、pull_request_review_comment
或 issue_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
工作流
可以使用 branches
或 branches-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 会将 pull_request
、issue_comment
、pull_request_review_comment
、pull_request_review
和 pull_request_target
事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。
当参与者第一次向公共存储库提交拉取请求时,拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息,请参阅“批准复刻中的工作流程运行”。
对于从分支存储库到专用存储库的拉取请求,工作流仅在启用时运行,请参阅“管理存储库的 GitHub Actions 设置”。
注意:Dependabot 拉取请求触发的工作流被视为来自存储库分支,也受到这些限制。
pull_request_comment
(使用 issue_comment
)
要在创建、编辑或删除对拉取请求(而不是拉取请求的差异)的注释时运行工作流,请使用 issue_comment
事件。 对于与拉取请求审查或拉取请求审查注释相关的活动,请使用 pull_request_review
或 pull_request_review_comment
事件。
pull_request_review
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
pull_request_review | - submitted - edited - dismissed | GITHUB_REF 分支上的最后一次合并提交 | PR 合并分支 refs/pull/:prNumber/merge |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
在提交、编辑或关闭拉取请求审阅时运行工作流程。 拉取请求审查是除正文评论和状态之外的一组拉取请求审查评论。 对于与拉取请求审查注释或拉取请求注释相关的活动,请改用 pull_request_review_comment
或 issue_comment
事件。 有关拉取请求审查 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“拉取”。
例如,可以在拉取请求审查的状态为 edited
或 dismissed
时运行工作流。
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 会将 pull_request
、issue_comment
、pull_request_review_comment
、pull_request_review
和 pull_request_target
事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。
当参与者第一次向公共存储库提交拉取请求时,拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息,请参阅“批准复刻中的工作流程运行”。
对于从分支存储库到专用存储库的拉取请求,工作流仅在启用时运行,请参阅“管理存储库的 GitHub Actions 设置”。
注意:Dependabot 拉取请求触发的工作流被视为来自存储库分支,也受到这些限制。
pull_request_review_comment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
pull_request_review_comment | - created - edited - deleted | GITHUB_REF 分支上的最后一次合并提交 | PR 合并分支 refs/pull/:prNumber/merge |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
在修改拉取请求审查评论时运行工作流程。 拉取请求审查评论是对拉取请求差异的评论。 对于与拉取请求审查或拉取请求注释相关的活动,请改用 pull_request_review
或 issue_comment
事件。 有关拉取请求审查注释 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“拉取”。
例如,可以在拉取请求审查注释的状态为 created
或 deleted
时运行工作流。
on:
pull_request_review_comment:
types: [created, deleted]
存储库分支中的工作流
默认情况下,工作流不在存储库分支中运行。 必须在存储库分支的“操作”选项卡中启用 GitHub Actions。
除 GITHUB_TOKEN
外,当从分支存储库触发工作流时,机密不会传递给运行器。 GITHUB_TOKEN
在存储库分支的拉取请求中具有只读权限。 有关详细信息,请参阅“自动令牌身份验证”。
复刻的仓库的拉取请求事件
对于从存储库分支到基础存储库的拉取请求,GitHub 会将 pull_request
、issue_comment
、pull_request_review_comment
、pull_request_review
和 pull_request_target
事件发送到基础存储库。 存储库分支上不会发生拉取请求事件。
当参与者第一次向公共存储库提交拉取请求时,拥有写入权限的维护者可能需要审核拉取请求上运行的工作流。 有关详细信息,请参阅“批准复刻中的工作流程运行”。
对于从分支存储库到专用存储库的拉取请求,工作流仅在启用时运行,请参阅“管理存储库的 GitHub Actions 设置”。
注意:Dependabot 拉取请求触发的工作流被视为来自存储库分支,也受到这些限制。
pull_request_target
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_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
事件的活动类型为 opened
、synchronize
或 reopened
时运行。 要按不同的活动类型触发工作流,请使用 types
关键字。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
在工作流程存储库中发生有关拉取请求的活动时运行工作流程。 例如,如果未指定任何活动类型,则工作流程将在打开或重新打开拉取请求时运行,或者在更新拉取请求的头部分支时运行。
此事件在拉取请求基础的上下文中运行,而不是像 pull_request
事件一样在合并提交上下文中运行。 这样可以防止从拉取请求的头部执行不安全的代码,以免更改您的仓库或窃取您在工作流程中使用的任何机密。 此事件允许您的工作流程对来自复刻的拉取请求执行标记或评论等操作。 如果需要从拉取请求构建或运行代码,请避免使用此事件。
为了确保存储库安全性,名称与特定模式匹配(例如类似于 SHA)的分支可能无法使用 pull_request_target
事件触发工作流。
警告:对于由 pull_request_target
事件触发的工作流,将授予 GITHUB_TOKEN
读/写存储库权限,除非指定了 permissions
密钥并且工作流可以访问机密,即使从分支触发也是如此。 虽然工作流程在拉取请求的基础上下文中运行,但您应该确保不在此事件中检出、生成或运行来自拉取请求的不受信任代码。 此外,任何缓存都与基本分支共享相同的作用域。 为帮助防止缓存中毒,如果缓存内容可能已更改,则不应保存缓存。 有关详细信息,请参阅 GitHub Security Lab 网站上的“确保 GitHub Actions 和工作流安全:阻止 pwn 请求”。
例如,可以在拉取请求的状态为 assigned
、opened
、synchronize
或 reopened
时运行工作流。
on:
pull_request_target:
types: [assigned, opened, synchronize, reopened]
基于拉取请求的主要分支或基础分支运行 pull_request_target
工作流
可以使用 branches
或 branches-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
工作流
可以使用 paths
或 paths-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_SHA | GITHUB_REF |
---|---|---|---|
push | 不适用 | 删除分支时,工作流运行中的 SHA(及其关联的 refs)将恢复为存储库的默认分支。 | 更新的引用 |
注意:可用于 GitHub Actions 的 Webhook 有效负载不包括 commit
对象中的 added
、removed
和 modified
属性。 您可以使用 API 检索完整的提交对象。 如需相关信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“提交”。
注意:一次推送三个以上的标记时,不会创建事件。
在推送提交或标记或使用模板创建存储库时运行工作流。
例如,可以在发生 push
事件时运行工作流。
on:
push
注意:当 push
Webhook 事件触发工作流运行时,操作 UI 的“推送者”字段会显示推送者的帐户,而不是作者或提交者的帐户。 但是,如果使用带有部署密钥的 SSH 身份验证将更改推送到存储库,则“推送者”字段将是在将部署密钥添加到存储库时验证部署密钥的存储库管理员。
仅在推送到特定分支时运行工作流程
可以使用 branches
或 branches-ignore
筛选器配置工作流,使其仅在推送特定分支时运行。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
例如,当有人推送到 main
或推送到以 releases/
开头的分支时,此工作流将运行。
on:
push:
branches:
- 'main'
- 'releases/**'
注意:如果同时使用 branches
筛选器和 paths
筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅在将包含 JavaScript (.js
) 文件更改的推送发送到名称以 releases/
开头的分支时,以下工作流才会运行:
on:
push:
branches:
- 'releases/**'
paths:
- '**.js'
仅在发生特定标记的推送时运行工作流程
可以使用 tags
或 tags-ignore
筛选器配置工作流,使其仅在推送特定标记时运行。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
例如,当有人推送以 v1.
开头的标记时,此工作流将运行。
on:
push:
tags:
- v1.**
仅当推送影响特定文件时才运行工作流程
可以使用 paths
或 paths-ignore
筛选器配置工作流,使其在推送到特定文件时运行。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
例如,当有人将更改推送到 JavaScript 文件 (.js
) 时,此工作流将运行:
on:
push:
paths:
- '**.js'
注意:如果同时使用 branches
筛选器和 paths
筛选器,则工作流将只在这两个筛选器都满足条件时运行。 例如,仅在将包含 JavaScript (.js
) 文件更改的推送发送到名称以 releases/
开头的分支时,以下工作流才会运行:
on:
push:
branches:
- 'releases/**'
paths:
- '**.js'
registry_package
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_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_SHA | GITHUB_REF |
---|---|---|---|
release | - published - unpublished - created - edited - deleted - prereleased - released | 标记的发行版中的最新提交 | 版本的标记参考 refs/tags/<tag_name> |
注意:多个活动类型会触发此事件。 有关每个活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:草稿版本的 created
、edited
或 deleted
活动类型不会触发工作流。 当您通过 GitHub 浏览器 UI 创建版本时,您的版本可能会自动另存为草稿。
注意:对于从草稿版本发布的预发行版本,prereleased
类型不会触发工作流,但 published
类型会触发。 如果想要在稳定版和预发行版发布时运行工作流,请订阅 published
而不是 released
和 prereleased
。
在存储库中发生发布活动时运行工作流程。 有关版本 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“发行版本”。
例如,可以在版本状态为 published
时运行工作流。
on:
release:
types: [published]
repository_dispatch
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
repository_dispatch | 自定义 | 默认分支上的最新提交 | 默认分支 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
若想要触发 GitHub 外部发生的活动的工作流,可以使用 GitHub API 触发名为 repository_dispatch
的 Webhook 事件。 有关详细信息,请参阅“存储库”。
发出创建 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_SHA | GITHUB_REF |
---|---|---|---|
不适用 | 不适用 | 默认分支上的最新提交 | 默认分支 |
注意: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 * * *'
多个 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_SHA | GITHUB_REF |
---|---|---|---|
status | 不适用 | 默认分支上的最新提交 | 不适用 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在 Git 提交状态更改时运行工作流程。 例如,可以将提交标记为 error
、failure
、pending
或 success
。 如果要提供有关状态更改的更多详细信息,可能需要使用 check_run
事件。 有关提交状态 API 的信息,请参阅 GraphQL API 文档中的“对象”或 REST API 文档中的“提交”。
例如,可以在发生 status
事件时运行工作流。
on:
status
如果要基于新的提交状态在工作流中运行作业,可以使用 github.event.state
上下文。 例如,以下工作流在提交状态发生更改时触发,但 if_error_or_failure
作业仅在新的提交状态为 error
或 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
watch
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
watch | - started | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 尽管仅支持 started
活动类型,但如果将来添加更多活动类型,则指定活动类型将使工作流保持特定。 有关每种活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
在工作流程的存储库加星标时运行工作流程。 有关拉取请求 API 的信息,请参阅 GraphQL API 文档中的“突变”或 REST API 文档中的“活动”。
例如,可以在某人为存储库加星标时(即监视事件的 started
活动类型)运行工作流。
on:
watch:
types: [started]
workflow_call
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
与调用方工作流程相同 | 不适用 | 与调用方工作流程相同 | 与调用方工作流程相同 |
workflow_call
用于指示一个工作流可以由另一个工作流调用。 当使用 workflow_call
事件触发工作流时,被调用工作流中的事件负载与调用工作流中的事件负载相同。 有关详细信息,请参阅“重新使用工作流”。
以下示例仅在从另一个工作流程调用时运行工作流程:
on: workflow_call
workflow_dispatch
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
workflow_dispatch | 不适用 | GITHUB_REF 分支或标记上的最后一次提交 | 收到调度的分支或标记 |
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
若要启用手动触发工作流,需要配置 workflow_dispatch
事件。 您可以使用 GitHub API、GitHub CLI或 GitHub 浏览器界面手动触发工作流程运行。 有关详细信息,请参阅“手动运行工作流程”。
on: workflow_dispatch
提供输入
您可以直接在工作流程中配置事件的自定义输入属性、默认输入值和必要输入。 触发事件时,可以提供 ref
和任何 inputs
。 当工作流运行时,可以访问 inputs
上下文中的输入值。 有关详细信息,请参阅“上下文”。
注释:
- 工作流还将接收
github.event.inputs
上下文中的输入。inputs
上下文和github.event.inputs
上下文中的信息完全相同,但inputs
上下文将布尔值保留为布尔值,而不是将它们转换为字符串。choice
类型解析为字符串,是单个可选选项。 inputs
的顶级属性的最大数目为 10。inputs
的最大有效负载为 65,535 个字符。
此示例定义了名为 logLevel
、tags
和 environment
的输入。 在运行工作流程时,可以将这些输入的值传递给工作流程。 然后,此工作流使用 inputs.logLevel
、inputs.tags
和 inputs.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_SHA | GITHUB_REF |
---|---|---|---|
workflow_run | - completed - requested - in_progress | 默认分支上的最新提交 | 默认分支 |
注意:多个活动类型会触发此事件。 重新运行工作流时不会出现 requested
活动类型。 有关每种活动类型的信息,请参阅“Webhook 事件和有效负载”。 默认情况下,所有活动类型都会触发在此事件上运行的工作流。 你可以使用 types
关键词将工作流运行限制为特定活动类型。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
注意:仅当工作流文件在默认分支上时,此事件才会触发工作流运行。
注意:不能使用 workflow_run
将超过三个工作流级别链接在一起。 例如,如果尝试触发五个工作流(名为 B
至 F
)在初始工作流 A
运行后依次运行(即:A
→ B
→ C
→ D
→ E
→ F
),工作流 E
和 F
将不会运行。
此事件在请求或完成工作流程运行时发生。 它允许您基于另一个工作流程的执行或完成来执行工作流程。 由 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'
将工作流限于基于分支的运行
可以使用 branches
或 branches-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@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!'
});