About events that trigger workflows
Workflow triggers are events that cause a workflow to run. For more information about how to use workflow triggers, see "Triggering a workflow."
Available events
Some events have multiple activity types. For these events, you can specify which activity types will trigger a workflow run. For more information about what each activity type means, see "Webhook events and payloads." Note that not all webhook events trigger workflows.
check_run
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
check_run | - created - rerequested - completed - requested_action | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when activity related to a check run occurs. 检查运行是检查套件中的单个测试。 For information, see "Getting started with the Checks API." For information about the check run APIs, see "CheckRun" in the GraphQL API documentation or "Checks" in the REST API documentation.
例如,您可以在检查运行为 rerequested
或 completed
时运行工作流程。
on:
check_run:
types: [rerequested, completed]
check_suite
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
check_suite | - completed | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." Although only the started
activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
注意:为防止递归工作流程,如果检查套件是由 GitHub Actions 创建的,则此事件不会触发工作流程。
Runs your workflow when check suite activity occurs. A check suite is a collection of the check runs created for a specific commit. Check suites summarize the status and conclusion of the check runs that are in the suite. For information, see "Getting started with the Checks API." For information about the check suite APIs, see "CheckSuite" in the GraphQL API documentation or "Checks" in the REST API documentation.
For example, you can run a workflow when a check suite has been completed
.
on:
check_suite:
types: [completed]
create
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
create | n/a | 创建的分支或� �记上的最新提交 | 创建的分支或� �记 |
Note: An event will not be created when you create more than three tags at once.
Runs your workflow when someone creates a Git reference (Git branch or tag) in the workflow's repository. For information about the APIs to create a Git reference, see "createRef" in the GraphQL API documentation or "Create a reference" in the REST API documentation.
例如,您可以在发生 create
事件时运行工作流程。
on:
create
delete
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
delete | n/a | 默认分支上的最新提交 | 默认分支 |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Note: An event will not be created when you delete more than three tags at once.
Runs your workflow when someone deletes a Git reference (Git branch or tag) in the workflow's repository. For information about the APIs to delete a Git reference, see "deleteRef" in the GraphQL API documentation or "Delete a reference" in the REST API documentation.
例如,您可以在发生 delete
事件时运行工作流程。
on:
delete
deployment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
deployment | n/a | 要部署的提交 | Branch or tag to be deployed (empty if created with a commit SHA) |
Runs your workflow when someone creates a deployment in the workflow's repository. 使用提交 SHA 创建的部署可能没有 Git 引用。 For information about the APIs to create a deployment, see "createDeployment" in the GraphQL API documentation or "Deployments" in the REST API documentation.
例如,您可以在发生 deployment
事件时运行工作流程。
on:
deployment
deployment_status
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
deployment_status | n/a | 要部署的提交 | 要部署的分支或� �记(提交时为空) |
Note: When a deployment status's state is set to inactive
, a workflow run will not be triggered.
Runs your workflow when a third party provides a deployment status. 使用提交 SHA 创建的部署可能没有 Git 引用。 For information about the APIs to create a deployment status, see "createDeploymentStatus" in the GraphQL API documentation or "Create a deployment status" in the REST API documentation.
例如,您可以在发生 deployment_status
事件时运行工作流程。
on:
deployment_status
复刻
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
复刻 | n/a | 默认分支上的最新提交 | 默认分支 |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when someone forks a repository. 有关 REST API 的信息,请参阅“创建复刻”。
例如,您可以在发生 fork
事件时运行工作流程。
on:
fork
gollum
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
gollum | n/a | 默认分支上的最新提交 | 默认分支 |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when someone creates or updates a Wiki page. 更多信息请参阅“关于 wiki”。
例如,您可以在发生 gollum
事件时运行工作流程。
on:
gollum
issue_comment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
issue_comment | - created - edited - deleted | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when an issue or pull request comment is created, edited, or deleted. For information about the issue comment APIs, see "IssueComment" in the GraphQL API documentation or "Issue comments" in the REST API documentation.
For example, you can run a workflow when an issue or pull request comment has been created
or deleted
.
on:
issue_comment:
types: [created, deleted]
issue_comment
on issues only or pull requests only
issue_comment
事件在评论问题和拉取请求时发生。 You can use the github.event.issue.pull_request
property in a conditional to take different action depending on whether the triggering object was an issue or pull request.
For example, this workflow will run the pr_commented
job only if the issue_comment
event originated from a pull request. It will run the issue_commented
job only if the issue_comment
event originated from an issue.
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_SHA | GITHUB_REF |
---|---|---|---|
议题 | - opened - edited - deleted - transferred - pinned - unpinned - closed - reopened - assigned - unassigned - labeled - unlabeled - locked - unlocked - milestoned - demilestoned | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when an issue in the workflow's repository is created or modified. For activity related to comments in an issue, use the issue_comment
event. 有关议题的更多信息,请参阅“关于议题”。 For information about the issue APIs, see "Issue" in the GraphQL API documentation or "Issues" in the REST API documentation.
例如,您可以在议题为 opened
、edited
或 milestoned
时运行工作流程。
on:
issues:
types: [opened, edited, milestoned]
� �签
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
� �签 | - created - edited - deleted | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when a label in your workflow's repository is created or modified. For more information about labels, see "Managing labels." For information about the label APIs, see "Label" in the GraphQL API documentation or "Labels" in the REST API documentation.
If you want to run your workflow when a label is added to or removed from an issue, pull request, or discussion, use the labeled
or unlabeled
activity types for the issues
, pull_request
, pull_request_target
, or discussion
events instead.
例如,您可以在� �签为 created
或 deleted
时运行工作流程。
on:
label:
types: [created, deleted]
里程碑
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
里程碑 | - created - closed - opened - edited - deleted | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when a milestone in the workflow's repository is created or modified. For more information about milestones, see "About milestones." For information about the milestone APIs, see "Milestone" in the GraphQL API documentation or "Milestones" in the REST API documentation.
If you want to run your workflow when an issue is added to or removed from a milestone, use the milestoned
or demilestoned
activity types for the issues
event instead.
例如,您可以在里程碑为 opened
或 deleted
时运行工作流程。
on:
milestone:
types: [opened, deleted]
page_build
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
page_build | n/a | 默认分支上的最新提交 | n/a |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when someone pushes to a branch that is the publishing source for GitHub Pages, if GitHub Pages is enabled for the repository. For more information about GitHub Pages publishing sources, see "Configuring a publishing source for your GitHub Pages site." 有关 REST API 的信息,请参阅“页面”。
例如,您可以在发生 page_build
事件时运行工作流程。
on:
page_build
project
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
project | - created - closed - reopened - edited - deleted | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 The edited
activity type refers to when a project board, not a column or card on the project board, is edited. For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Note: This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository.
Runs your workflow when a project board is created or modified. For activity related to cards or columns in a project board, use the project_card
or project_column
events instead. For more information about project boards, see "About project boards." For information about the project board APIs, see "Project" in the GraphQL API documentation or "Projects" in the REST API documentation.
例如,您可以在项目为 created
或 deleted
时运行工作流程。
on:
project:
types: [created, deleted]
project_card
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
project_card | - created - moved - converted to an issue- edited - deleted | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Note: This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository.
Runs your workflow when a card on a project board is created or modified. For activity related to project boards or columns in a project board, use the project
or project_column
event instead. For more information about project boards, see "About project boards." For information about the project card APIs, see "ProjectCard" in the GraphQL API documentation or "Project cards" in the REST API documentation.
For example, you can run a workflow when a project card has been created
or deleted
.
on:
project_card:
types: [created, deleted]
project_column
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
project_column | - created - updated - moved - deleted | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Note: This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository.
Runs your workflow when a column on a project board is created or modified. For activity related to project boards or cards in a project board, use the project
or project_card
event instead. For more information about project boards, see "About project boards." For information about the project column APIs, see "Project Column" in the GraphQL API documentation or "Project columns" in the REST API documentation.
例如,您可以在项目列为 created
或 deleted
时运行工作流程。
on:
project_column:
types: [created, deleted]
public
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
public | n/a | 默认分支上的最新提交 | 默认分支 |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when your workflow's repository changes from private to 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 | GITHUB_REF 分支上的最新合并提交 | PR 合并分支 refs/pull/:prNumber/merge |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." By default, a workflow only runs when a pull_request
event's activity type is opened
, synchronize
, or reopened
. You can specify different activity types using the types
keyword. 更多信息请参阅“GitHub Actions 的工作流程语法”。
Note: By default, only the opened
, synchronize
, and reopened
activity types trigger workflows that run on the pull_request
event. To trigger workflows by different activity types, use the types
keyword.
Note: Workflows will not run on pull_request
activity if the pull request has a merge conflict. 必须先解决合并冲突。
Conversely, workflows with the pull_request_target
event will run even if the pull request has a merge conflict. Before using the pull_request_target
trigger, you should be aware of the security risks. For more information, see pull_request_target
.
Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. For activity related to pull request reviews, pull request review comments, or pull request comments, use the pull_request_review
, pull_request_review_comment
, or issue_comment
events instead. For information about the pull request APIs, see "PullRequest" in the GraphQL API documentation or "Pull requests" in the REST API documentation.
Note that GITHUB_SHA
for this event is the last merge commit of the pull request merge branch. If you want to get the commit ID for the last commit to the head branch of the pull request, use github.event.pull_request.head.sha
instead.
For example, you can run a workflow when a pull request has been opened or reopened.
on:
pull_request:
types: [opened, reopened]
You can use the event context to further control when jobs in your workflow will run. For example, this workflow will run when a review is requested on a pull request, but the specific_review_requested
job will only run when a review by octo-team
is requested.
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'
Running your workflow based on the head or base branch of a pull request
You can use the branches
or branches-ignore
filter to configure your workflow to only run on pull requests that target specific branches. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when someone opens a pull request that targets a branch whose name starts with releases/
:
on:
pull_request:
types:
- opened
branches:
- 'releases/**'
Note: If you use both the branches
filter and the paths
filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js
) file is opened on a branch whose name starts with releases/
:
on:
pull_request:
types:
- opened
branches:
- 'releases/**'
paths:
- '**.js'
To run a job based on the pull request's head branch name (as opposed to the pull request's base branch name), use the github.head_ref
context in a conditional. For example, this workflow will run whenever a pull request is opened, but the run_if
job will only execute if the head of the pull request is a branch whose name starts with releases/
:
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/'"
Running your workflow based on files changed in a pull request
You can also configure your workflow to run when a pull request changes specific files. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when a pull request includes a change to a JavaScript file (.js
):
on:
pull_request:
paths:
- '**.js'
Note: If you use both the branches
filter and the paths
filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js
) file is opened on a branch whose name starts with releases/
:
on:
pull_request:
types:
- opened
branches:
- 'releases/**'
paths:
- '**.js'
Running your workflow when a pull request merges
When a pull request merges, the pull request is automatically closed. To run a workflow when a pull request merges, use the pull_request
closed
event type along with a conditional that checks the merged
value of the event. For example, the following workflow will run whenever a pull request closes. The if_merged
job will only run if the pull request was also 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
Workflows in forked repositories
Workflows don't run in forked repositories by default. 您必须在复刻仓库的 Actions(操作)选项卡中启用 GitHub Actions。
除了 GITHUB_TOKEN
以外,从复刻的仓库触发工作流程时密� �不会� 递给运行程序。 The GITHUB_TOKEN
has read-only permissions in forked repositories. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。
复刻的仓库的拉取请求事件
For pull requests from a forked repository to the base repository, GitHub Enterprise Server sends the pull_request
, issue_comment
, pull_request_review_comment
, pull_request_review
, and pull_request_target
events to the base repository. No pull request events occur on the forked repository.
注:如果从复刻仓库打开拉取请求,工作流程不会在私有基础仓库上运行。
注意:由 Dependabot 拉取请求触发的工作流程被视为来自复刻的仓库,也受到这些限制。
pull_request_comment
(use issue_comment
)
To run your workflow when a comment on a pull request (not on a pull request's diff) is created, edited, or deleted, use the issue_comment
event. For activity related to pull request reviews or pull request review comments, use the pull_request_review
or pull_request_review_comment
events.
pull_request_review
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
pull_request_review | - submitted - edited - dismissed | GITHUB_REF 分支上的最新合并提交 | PR 合并分支 refs/pull/:prNumber/merge |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
Runs your workflow when a pull request review is submitted, edited, or dismissed. A pull request review is a group of pull request review comments in addition to a body comment and a state. For activity related to pull request review comments or pull request comments, use the pull_request_review_comment
or issue_comment
events instead. For information about the pull request review APIs, see "PullRequestReview" in the GraphQL API documentation or "Pull request reviews" in the REST API documentation.
例如,您可以在拉取请求审查为 edited
或 dismissed
时运行工作流程。
on:
pull_request_review:
types: [edited, dismissed]
Running a workflow when a pull request is approved
To run your workflow when a pull request has been approved, you can trigger your workflow with the submitted
type of pull_request_review
event, then check the review state with the github.event.review.state
property. For example, this workflow will run whenever a pull request review is submitted, but the approved
job will only run if the submitted review is an approving review:
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"
Workflows in forked repositories
Workflows don't run in forked repositories by default. 您必须在复刻仓库的 Actions(操作)选项卡中启用 GitHub Actions。
除了 GITHUB_TOKEN
以外,从复刻的仓库触发工作流程时密� �不会� 递给运行程序。 The GITHUB_TOKEN
has read-only permissions in forked repositories. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。
复刻的仓库的拉取请求事件
For pull requests from a forked repository to the base repository, GitHub Enterprise Server sends the pull_request
, issue_comment
, pull_request_review_comment
, pull_request_review
, and pull_request_target
events to the base repository. No pull request events occur on the forked repository.
注:如果从复刻仓库打开拉取请求,工作流程不会在私有基础仓库上运行。
注意:由 Dependabot 拉取请求触发的工作流程被视为来自复刻的仓库,也受到这些限制。
pull_request_review_comment
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
pull_request_review_comment | - created - edited - deleted | GITHUB_REF 分支上的最新合并提交 | PR 合并分支 refs/pull/:prNumber/merge |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
Runs your workflow when a pull request review comment is modified. A pull request review comment is a comment on a pull request's diff. For activity related to pull request reviews or pull request comments, use the pull_request_review
or issue_comment
events instead. For information about the pull request review comment APIs, see "PullRequestReviewComment" in the GraphQL API documentation or "Review comments" in the REST API documentation.
例如,您可以在拉取请求审查评论为 created
或 deleted
时运行工作流程。
on:
pull_request_review_comment:
types: [created, deleted]
Workflows in forked repositories
Workflows don't run in forked repositories by default. 您必须在复刻仓库的 Actions(操作)选项卡中启用 GitHub Actions。
除了 GITHUB_TOKEN
以外,从复刻的仓库触发工作流程时密� �不会� 递给运行程序。 The GITHUB_TOKEN
has read-only permissions in forked repositories. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。
复刻的仓库的拉取请求事件
For pull requests from a forked repository to the base repository, GitHub Enterprise Server sends the pull_request
, issue_comment
, pull_request_review_comment
, pull_request_review
, and pull_request_target
events to the base repository. No pull request events occur on the forked repository.
注:如果从复刻仓库打开拉取请求,工作流程不会在私有基础仓库上运行。
注意:由 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 | PR 基分支上的最后一次提交 | PR 基础分支 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,工作流程仅在 pull_request_target
的活动类型为 opened
、synchronize
或 reopened
时运行。 要让更多活动类型触发工作流程,请使用 types
关键词。 You can specify different activity types using the types
keyword. 更多信息请参阅“GitHub Actions 的工作流程语法”。
Note: By default, only the opened
, synchronize
, and reopened
activity types trigger workflows that run on the pull_request
event. To trigger workflows by different activity types, use the types
keyword.
Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated.
This event runs in the context of the base of the pull request, rather than in the context of the merge commit, as the pull_request
event does. This prevents execution of unsafe code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows your workflow to do things like label or comment on pull requests from forks. Avoid using this event if you need to build or run code from the pull request.
Warning: For workflows that are triggered by the pull_request_target
event, the GITHUB_TOKEN
is granted read/write repository permission unless the permissions
key is specified and the workflow can access secrets, even when it is triggered from a fork. 虽然工作流程在拉取请求的基础上下文中运行,但您应该确保不在此事件中检出、生成或运行来自拉取请求的不受信任代� �。 Additionally, any caches share the same scope as the base branch. To help prevent cache poisoning, you should not save the cache if there is a possibility that the cache contents were altered. 更多信息请参阅 GitHub 安全实验室网站上的“保持 GitHub Actions 和工作流程安全:阻止 pwn 请求”。
例如,您可以在拉取请求为 assigned
、opened
、synchronize
或 reopened
时运行工作流程。
on:
pull_request_target:
types: [assigned, opened, synchronize, reopened]
Running your workflow based on the head or base branch of a pull request
You can use the branches
or branches-ignore
filter to configure your workflow to only run on pull requests that target specific branches. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when someone opens a pull request that targets a branch whose name starts with releases/
:
on:
pull_request_target:
types:
- opened
branches:
- 'releases/**'
Note: If you use both the branches
filter and the paths
filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js
) file is opened on a branch whose name starts with releases/
:
on:
pull_request_target:
types:
- opened
branches:
- 'releases/**'
paths:
- '**.js'
To run a job based on the pull request's head branch name (as opposed to the pull request's base branch name), use the github.head_ref
context in a conditional. For example, this workflow will run whenever a pull request is opened, but the run_if
job will only execute if the head of the pull request is a branch whose name starts with releases/
:
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/'"
Running your workflow based on files changed in a pull request
You can use the paths
or paths-ignore
filter to configure your workflow to run when a pull request changes specific files. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when a pull request includes a change to a JavaScript file (.js
):
on:
pull_request_target:
paths:
- '**.js'
Note: If you use both the branches
filter and the paths
filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a pull request that includes a change to a JavaScript (.js
) file is opened on a branch whose name starts with releases/
:
on:
pull_request_target:
types:
- opened
branches:
- 'releases/**'
paths:
- '**.js'
Running your workflow when a pull request merges
When a pull request merges, the pull request is automatically closed. To run a workflow when a pull request merges, use the pull_request_target
closed
event type along with a conditional that checks the merged
value of the event. For example, the following workflow will run whenever a pull request closes. The if_merged
job will only run if the pull request was also merged.
on:
pull_request_target:
types:
- closed
jobs:
if_merged:
if: github.event.pull_request_target.merged == true
runs-on: ubuntu-latest
steps:
- run: |
echo The PR was merged
推送
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
推送 | n/a | 推送的提交,除非� 除分支(当它是默认分支时) | 更新的引用 |
注:适用于 GitHub Actions 的 web 挂钩有效负载在 commit
对象中不包括 added
、removed
和 modified
属性。 You can retrieve the full commit object using the API. For information, see "Commit" in the GraphQL API documentation or "Get a commit" in the REST API documentation.
Note: An event will not be created when you push more than three tags at once.
Runs your workflow when you push a commit or tag.
例如,您可以在发生 push
事件时运行工作流程。
on:
push
Running your workflow only when a push to specific branches occurs
You can use the branches
or branches-ignore
filter to configure your workflow to only run when specific branches are pushed. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when someone pushes to main
or to a branch that starts with releases/
.
on:
push:
branches:
- 'main'
- 'releases/**'
Note: If you use both the branches
filter and the paths
filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a push that includes a change to a JavaScript (.js
) file is made to a branch whose name starts with releases/
:
on:
push:
branches:
- 'releases/**'
paths:
- '**.js'
Running your workflow only when a push of specific tags occurs
You can use the tags
or tags-ignore
filter to configure your workflow to only run when specific tags or are pushed. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when someone pushes a tag that starts with v1.
.
on:
push:
tags:
- v1.**
Running your workflow only when a push affects specific files
You can use the paths
or paths-ignore
filter to configure your workflow to run when a push to specific files occurs. 更多信息请参阅“GitHub Actions 的工作流程语法”。
For example, this workflow will run when someone pushes a change to a JavaScript file (.js
):
on:
push:
paths:
- '**.js'
Note: If you use both the branches
filter and the paths
filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a push that includes a change to a JavaScript (.js
) file is made to a branch whose name starts with releases/
:
on:
push:
branches:
- 'releases/**'
paths:
- '**.js'
registry_package
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
registry_package | - published - updated | Commit of the published package | 已发布软件包的分支或� �签 |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when activity related to GitHub Packages occurs in your repository. 更多信息请参阅“GitHub Packages 文档”。
例如,您可以在软件包为 published
时运行工作流程。
on:
registry_package:
types: [published]
发行版
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
发行版 | - published - unpublished - created - edited - deleted - prereleased - released | � �记的发行版中的最新提交 | Tag ref of release refs/tags/<tag_name> |
Note: 多个活动类型会触发此事件。 For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
Note: Workflows are not triggered for the created
, edited
, or deleted
activity types for draft releases. When you create your release through the GitHub Enterprise Server browser UI, your release may automatically be saved as a draft.
注意:prereleased
类型不会触发从草稿版本预发布,但 published
类型会触发。 如果您希望工作流程在稳定和预发布时运行,请订阅 published
而不是 released
和 prereleased
。
Runs your workflow when release activity in your repository occurs. For information about the release APIs, see "Release" in the GraphQL API documentation or "Releases" in the REST API documentation.
例如,您可以在版本发布为 published
时运行工作流程。
on:
release:
types: [published]
repository_dispatch
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
repository_dispatch | 自定义 | 默认分支上的最新提交 | 默认分支 |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
当您想要触发在 GitHub Enterprise Server 外发生的活动的工作流程时,可以使用 GitHub Enterprise Server API 触发名为 repository_dispatch
的 web 挂钩事件。 更多信息请参阅“创建仓库调度事件”。
When you make a request to create a repository_dispatch
event, you must specify an event_type
to describe the activity type. By default, all repository_dispatch
activity types trigger a workflow to run. You can use the types
keyword to limit your workflow to run when a specific event_type
value is sent in the repository_dispatch
webhook payload.
on:
repository_dispatch:
types: [on-demand-test]
Any data that you send through the client_payload
parameter will be available in the github.event
context in your workflow. For example, if you send this request body when you create a repository dispatch event:
{
"event_type": "test_result",
"client_payload": {
"passed": false,
"message": "Error: timeout"
}
}
then you can access the payload in a workflow like this:
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_SHA | GITHUB_REF |
---|---|---|---|
n/a | n/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 * * *'
A single workflow can be triggered by multiple schedule
events. You can access the schedule event that triggered the workflow through the github.event.schedule
context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday
step on Monday and 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 * * * * runs at every minute 15 of every hour of every day. |
, | 值列表分隔符 | 2,10 4,5 * * * 在每天第 4 和第 5 小时的第 2 和第 10 分钟运行。 |
- | 值的范围 | 30 4-6 * * * runs at minute 30 of the 4th, 5th, and 6th hour. |
/ | 步骤值 | 20/15 * * * * 从第 20 分钟到第 59 分钟每隔 15 分钟运行(第 20、35 和 50 分钟)。 |
注: GitHub Actions 不支持非� �准语法 @yearly
、@monthly
、@weekly
、@daily
、@hourly
和 @reboot
。
您可以使用 crontab guru 帮助生成计划任务语法并确认它在何时运行。 为帮助您开始,我们还提供了一系列 crontab guru 示例。
计划工作流程的通知将发送给最后修改工作流程文件中的 cron 语法的用户。 For more information, see "Notifications for workflow runs."
状态
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
状态 | n/a | 默认分支上的最新提交 | n/a |
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when the status of a Git commit changes. For example, commits can be marked as error
, failure
, pending
, or success
. If you want to provide more details about the status change, you may want to use the check_run
event. For information about the commit status APIs, see "Status" in the GraphQL API documentation or "Statuses" in the REST API documentation.
例如,您可以在发生 status
事件时运行工作流程。
on:
status
If you want to run a job in your workflow based on the new commit state, you can use the github.event.state
context. For example, the following workflow triggers when a commit status changes, but the if_error_or_failure
job only runs if the new commit state is 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_SHA | GITHUB_REF |
---|---|---|---|
查看 | - started | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 Although only the started
activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Runs your workflow when the workflow's repository is starred. For information about the pull request APIs, see "addStar" in the GraphQL API documentation or "Starring" in the REST API documentation.
For example, you can run a workflow when someone stars a repository, which is the started
activity type for a watch event.
on:
watch:
types: [started]
workflow_dispatch
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
workflow_dispatch | n/a | GITHUB_REF 分支上的最新提交 | 收到了分发的分支 |
To manually trigger a workflow, use the workflow_dispatch
event. You can manually trigger a workflow run using the GitHub Enterprise Server API, GitHub CLI, or GitHub Enterprise Server browser interface. 更多信息请参阅“手动配置工作流程。
on: workflow_dispatch
Providing inputs
您可以直接在工作流程中配置事件的自定义输入属性、默认输入值和必要输入。 When you trigger the event, you can provide the ref
and any inputs
. 当工作流程运行时,您可以访问 github.event.inputs
上下文中的输入值。 更多信息请参阅“上下文”。
此示例定义了 name
和 home
输入,并使用 github.event.inputs.name
和 github.event.inputs.home
上下文打印。 如果未提供 home
,则打印默认值“The Octoverse”。
name: Manually triggered workflow
on:
workflow_dispatch:
inputs:
name:
description: 'Person to greet'
required: true
default: 'Mona the Octocat'
home:
description: 'location'
required: false
default: 'The Octoverse'
jobs:
say_hello:
runs-on: ubuntu-latest
steps:
- run: |
echo Hello $NAME!
echo -in $HOME
env:
NAME: ${{ github.event.inputs.name }}
HOME: ${{ github.event.inputs.home }}
workflow_run
Web 挂钩事件有效负载 | 活动类型 | GITHUB_SHA | GITHUB_REF |
---|---|---|---|
workflow_run | - completed - requested | 默认分支上的最新提交 | 默认分支 |
Note: 多个活动类型会触发此事件。 The requested
activity type does no occur when a workflow is re-run. For information about each activity type, see "Webhook events and payloads." 默认情况下,所有活动类型都会触发一个工作流程。 您可以使用 types(类型)
关键词将工作流程限制为针对特定活动类型。 更多信息请参阅“GitHub Actions 的工作流程语法”。
注:仅当工作流程文件在默认分支上时,此事件才会触发工作流程运行。
Note: You can't use workflow_run
to chain together more than three levels of workflows. For example, if you attempt to trigger five workflows (named B
to F
) to run sequentially after an initial workflow A
has run (that is: A
→ B
→ C
→ D
→ E
→ F
), workflows E
and F
will not be run.
This event occurs when a workflow run is requested or completed. It allows you to execute a workflow based on execution or completion of another workflow. 由 workflow_run
事件启动的工作流程能够访问密钥和写入令牌,即使以前的工作流程不能访问也一� �。 这在以前的工作流程有意未获权限的情况下很有用,但您需要在以后的工作流程中采取特权行动。
在此示例中,工作流程配置为在单独的“运行测试”工作流程完成后运行。
on:
workflow_run:
workflows: [Run Tests]
types:
- completed
If you specify multiple workflows
for the workflow_run
event, only one of the workflows needs to run. For example, a workflow with the following trigger will run whenever the "Staging" workflow or the "Lab" workflow completes.
on:
workflow_run:
workflows: [Staging, Lab]
types:
- completed
Running a workflow based on the conclusion of another workflow
A workflow run is triggered regardless of the conclusion of the previous workflow. If you want to run a job or step based on the result of the triggering workflow, you can use a conditional with the github.event.workflow_run.conclusion
property. For example, this workflow will run whenever a workflow named "Build" completes, but the on-success
job will only run if the "Build" workflow succeeded, and the on-failure
job will only run if the "Build" workflow failed:
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'
Limiting your workflow to run based on branches
You can use the branches
or branches-ignore
filter to specify what branches the triggering workflow must run on in order to trigger your workflow. For more information, see "Workflow syntax for GitHub Actions." For example, a workflow with the following trigger will only run when the workflow named Build
runs on a branch named canary
.
on:
workflow_run:
workflows: [Build]
types: [requested]
branches: [canary]
Using data from the triggering workflow
You can access the workflow_run
event payload that corresponds to the workflow that triggered your workflow. For example, if your triggering workflow generates artifacts, a workflow triggered with the workflow_run
event can access these artifacts.
The following workflow uploads data as an artifact. (In this simplified example, the data is the pull request number.)
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@v2
with:
name: pr_number
path: pr/
When a run of the above workflow completes, it triggers a run of the following workflow. The following workflow uses the github.event.workflow_run
context and the GitHub Enterprise Server REST API to download the artifact that was uploaded by the above workflow, unzips the downloaded artifact, and comments on the pull request whose number was uploaded as an artifact.
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@v5
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@v5
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!'
});