关于工作流程触发器
工作流程触发器是导致工作流程运行的事件。 这些事件可以是:
- 工作流程存储库中发生的事件
- 在 GitHub 之外发生并在 GitHub 上触发
repository_dispatch
事件的事件 - 预定时间
- 手动
例如,您可以将工作流程配置为在推送到存储库的默认分支、创建发行版或打开议题时运行。
工作流触发器使用 on
键定义。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
以下步骤将触发工作流程运行:
-
存储库上发生事件。 该事件具有关联的提交 SHA 和 Git 引用。
-
GitHub 在存储库的根的
.github/workflows
目录中搜索事件的关联提交 SHA 或 Git 引用中存在的工作流文件。 -
对于具有与触发事件匹配的
on:
值的任何工作流,触发工作流运行。 某些事件还要求工作流程文件位于存储库的默认分支上才能运行。每个工作流程运行都将使用事件的关联提交 SHA 或 Git ref 中存在的工作流程版本。 当工作流运行时,GitHub 会在运行器环境中设置
GITHUB_SHA
(提交 SHA)和GITHUB_REF
(Git 引用)环境变量。 有关详细信息,请参阅“在变量中存储信息”。
从工作流程触发工作流程
使用存储库的 GITHUB_TOKEN
执行任务时,GITHUB_TOKEN
触发事件,除 workflow_dispatch
和 repository_dispatch
以外, 将不会创建新的工作流运行。 这可以防止意外创建递归工作流程运行。 例如,如果工作流运行使用存储库的 GITHUB_TOKEN
推送代码,则即使存储库包含配置为在 push
事件发生时运行的工作流,新工作流也不会运行。 有关详细信息,请参阅“自动令牌身份验证”。
如果确实要从工作流运行中触发工作流,可以使用 GitHub App 安装访问令牌或 personal access token(而不是 GITHUB_TOKEN
)来触发需要令牌的事件。
如果使用 GitHub App,则需要创建 GitHub App 并将应用 ID 和私钥存储为机密。 有关详细信息,请参阅“使用 GitHub Actions 工作流中的 GitHub App 发出经过身份验证的 API 请求”。 如果使用 personal access token,则需要创建 personal access token 并将其存储为机密。 有关创建 personal access token 的详细信息,请参阅“管理个人访问令牌”。 有关存储机密的详细信息,请参阅“在 GitHub Actions 中使用机密”。
为了最大限度地降低 GitHub Actions 使用成本,请确保不要创建递归或意外的工作流程。
例如,以下工作流使用 personal access token(存储为称为 MY_TOKEN
的机密)通过 GitHub CLI 向问题添加标签。 添加标签时运行的任何工作流程都将在执行此步骤后运行。
on:
issues:
types:
- opened
jobs:
label_issue:
runs-on: ubuntu-latest
steps:
- env:
GH_TOKEN: ${{ secrets.MY_TOKEN }}
ISSUE_URL: ${{ github.event.issue.html_url }}
run: |
gh issue edit $ISSUE_URL --add-label "triage"
相反,以下工作流使用 GITHUB_TOKEN
向问题添加标签。 它不会触发在添加标签时运行的任何工作流程。
on:
issues:
types:
- opened
jobs:
label_issue:
runs-on: ubuntu-latest
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ISSUE_URL: ${{ github.event.issue.html_url }}
run: |
gh issue edit $ISSUE_URL --add-label "triage"
使用事件触发工作流程
使用 on
键指定触发工作流的事件。 有关可以使用的事件的详细信息,请参阅“触发工作流的事件”。
使用单个事件
例如,当推送到工作流存储库中的任何分支时,将运行具有以下 on
值的工作流:
on: push
使用多个事件
可以指定单个事件或多个事件。 例如,当推送到存储库中的任何分支或有人创建存储库的分支时,将运行具有以下 on
值的工作流:
on: [push, fork]
如果指定多个事件,仅需发生其中一个事件就可触发工作流。 如果触发工作流的多个事件同时发生,将触发多个工作流运行。
将活动类型和筛选器用于多个事件
您可以使用活动类型和筛选器进一步控制工作流程的运行时间。 有关详细信息,请参阅使用事件活动类型和使用筛选器。 如果为事件指定活动类型或筛选器,并且针对多个事件指定工作流触发器,则必须单独配置每个事件。 必须为所有事件附加冒号 (:
),包括没有配置的事件。
例如,具有以下 on
值的工作流将在以下情况下运行:
- 创建标签
- 推送到存储库中的
main
分支 - 推送到启用了 GitHub Pages 的分支
on:
label:
types:
- created
push:
branches:
- main
page_build:
使用事件活动类型
某些事件具有活动类型,可让你更好地控制工作流的运行时间。 使用 on.<event_name>.types
定义将触发工作流运行的事件活动类型。
例如,issue_comment
事件具有 created
、edited
和 deleted
活动类型。 如果工作流在 label
事件上触发,则每当创建、编辑或删除标签时,它都会运行。 如果为 created
事件指定 label
活动类型,则工作流将在创建标签时运行,但不会在编辑或删除标签时运行。
on:
label:
types:
- created
如果指定多个活动类型,则只需要发生其中一种事件活动类型就可触发工作流。 如果触发工作流的多个事件活动类型同时发生,则将触发多个工作流运行。 例如,创建或标记问题时,会触发以下工作流。 如果创建了一个带两个标签的问题,则将启动三个工作流运行:一个用于创建问题的事件,另外两个用于两个标记问题的事件。
on:
issues:
types:
- opened
- labeled
有关每个事件及其活动类型的详细信息,请参阅“触发工作流的事件”。
使用筛选器
某些事件具有筛选器,可让你更好地控制工作流的运行时间。
例如,push
事件具有 branches
筛选器,该筛选器仅在发生目标为与 branches
筛选器匹配的分支的推送时(而不是在发生任何推送时)运行工作流。
on:
push:
branches:
- main
- 'releases/**'
使用筛选器定位拉取请求事件的特定分支
使用 pull_request
和 pull_request_target
事件时,可以将工作流配置为仅针对面向特定分支的拉取请求运行。
如果要包含分支名称模式或同时包含和排除分支名称模式,请使用 branches
筛选器。 只希望排除分支名称时,请使用 branches-ignore
筛选器。 不能对工作流中的同一事件同时使用 branches
和 branches-ignore
筛选器。
如果你同时定义 branches
/branches-ignore
和 paths
/paths-ignore
,则工作流将只在这两个筛选器都满足条件时运行。
branches
和 branches-ignore
关键词接受使用 *
、**
、+
、?
和 !
等字符匹配多个路径名称的 glob 模式。 如果名称包含其中任一字符,而你想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的详细信息,请参阅“GitHub Actions 的工作流语法”。
示例:包括分支
示例:排除分支
当模式与 branches-ignore
模式匹配时,工作流将不会运行。 在 branches-ignore
中定义的模式根据 Git 引用的名称进行评估。 例如,除非拉取请求面向以下内容,否则每当有 pull_request
事件时,以下工作流都会运行:
- 名为
mona/octocat
的分支 (refs/heads/mona/octocat
) - 名称匹配
releases/**-alpha
的分支,如releases/beta/3-alpha
(refs/heads/releases/beta/3-alpha
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
示例:包括和排除分支
不能在单个工作流中使用 branches
和 branches-ignore
筛选同一事件。 如果要同时包括和排除单个事件的分支模式,请使用 branches
筛选器以及 !
字符来指示应排除哪些分支或标记。
如果使用字符 !
定义分支,则还必须至少定义一个没有 !
字符的分支。 如果只想排除分支,请改用 branches-ignore
。
您定义模式事项的顺序。
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除 Git 引用。 - 否定匹配后的匹配肯定模式将再次包含 Git 引用。
以下工作流将在针对面向 releases/10
或 releases/beta/mona
的拉取请求的 pull_request
事件上运行,但不针对面向 releases/10-alpha
或 releases/beta/3-alpha
的拉取请求,由于负模式,!releases/**-alpha
将遵循正模式。
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
使用筛选器定位推送事件的特定分支或标记
使用 push
事件时,可以将工作流配置为在特定分支或标记上运行。
如果要包含分支名称模式或要同时包含和排除分支名称模式,请使用 branches
筛选器。 只希望排除分支名称时,请使用 branches-ignore
筛选器。 不能对工作流中的同一事件同时使用 branches
和 branches-ignore
筛选器。
如果要包含标记名称模式或要同时包含和排除标记名称模式,请使用 tags
筛选器。 只需要排除标记名称模式时,请使用 tags-ignore
筛选器。 不能对工作流中的同一事件同时使用 tags
和 tags-ignore
筛选器。
如果仅定义 tags
/tags-ignore
或 branches
/branches-ignore
,则工作流不会针对影响未定义的 Git ref 的事件运行。如果两者 tags
/tags-ignore
或 branches
/branches-ignore
均未定义,则工作流将针对影响分支或标记的事件运行。 如果你同时定义 branches
/branches-ignore
和 paths
/paths-ignore
,则工作流将只在这两个筛选器都满足条件时运行。
branches
、branches-ignore
、tags
和 tags-ignore
关键词接受使用 *
、**
、+
、?
和 !
等字符匹配多个分支或标记名称的 glob 模式。 如果名称包含其中任一字符,而你想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的详细信息,请参阅“GitHub Actions 的工作流语法”。
示例:包括分支和标记
在 branches
和 tags
中定义的模式根据 Git ref 的名称进行评估。 例如,当以下项出现 push
事件时,将运行以下工作流:
- 名为
main
的分支 (refs/heads/main
) - 名为
mona/octocat
的分支 (refs/heads/mona/octocat
) - 名称以
releases/
开头的分支,如releases/10
(refs/heads/releases/10
) - 名为
v2
的标记 (refs/tags/v2
) - 名称以
v1.
开头的标记,如v1.9.1
(refs/tags/v1.9.1
)
on:
push:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
# Sequence of patterns matched against refs/tags
tags:
- v2
- v1.*
示例:排除分支和标记
当某个模式与 branches-ignore
或 tags-ignore
模式匹配时,工作流将不会运行。 在 branches
和 tags
中定义的模式根据 Git ref 的名称进行评估。 例如,只要出现 push
事件,就会运行以下工作流,除非以下项出现 push
事件:
- 名为
mona/octocat
的分支 (refs/heads/mona/octocat
) - 名称与
releases/**-alpha
匹配的分支,如releases/beta/3-alpha
(refs/heads/releases/beta/3-alpha
) - 名为
v2
的标记 (refs/tags/v2
) - 名称以
v1.
开头的标记,如v1.9
(refs/tags/v1.9
)
on:
push:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
# Sequence of patterns matched against refs/tags
tags-ignore:
- v2
- v1.*
示例:包括和排除分支和标记
不能在一个工作流中使用 branches
和 branches-ignore
筛选同一事件。 同样,不能在一个工作流中使用 tags
和 tags-ignore
筛选同一事件。 如果要同时包括和排除一个事件的分支或标记模式,请使用 branches
或 tags
筛选器以及 !
字符来指示应排除哪些分支或标记。
如果使用字符 !
定义分支,则还必须至少定义一个没有 !
字符的分支。 如果只想排除分支,请改用 branches-ignore
。 同样,如果使用字符 !
定义标记,则还必须至少定义一个没有 !
字符的标记。 如果只想排除标记,请改用 tags-ignore
。
您定义模式事项的顺序。
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除 Git 引用。 - 否定匹配后的匹配肯定模式将再次包含 Git 引用。
以下工作流将在推送到 releases/10
或 releases/beta/mona
时运行,但不在推送到 releases/10-alpha
或 releases/beta/3-alpha
时运行,因为否定模式 !releases/**-alpha
遵循肯定模式。
on:
push:
branches:
- 'releases/**'
- '!releases/**-alpha'
使用筛选器定位拉取请求或推送事件的特定路径
使用 push
和 pull_request
事件时,可以配置工作流以根据更改的文件路径运行。 路径筛选器不会针对标记的推送进行评估。
如果想要包括文件路径模式或想要同时包括和排除文件路径模式,请使用 paths
筛选器。 如果只想排除文件路径模式,请使用 paths-ignore
筛选器。 不能对工作流中的同一事件同时使用 paths
和 paths-ignore
筛选器。 如果要同时包括和排除单个事件的路径模式,请使用前缀为 !
字符的 paths
筛选器来指示应排除哪些路径。
Note
您定义 paths
模式事项的顺序:
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除路径。 - 否定匹配后的匹配肯定模式将再次包含路径。
如果你同时定义 branches
/branches-ignore
筛选器和 paths
/paths-ignore
筛选器,则工作流将只在这两个筛选器都满足条件时运行。
paths
和 paths-ignore
关键字接受使用 *
和 **
通配符匹配多个路径名的 glob 模式。 有关详细信息,请参阅“GitHub Actions 的工作流语法”。
示例:包括路径
如果至少一个路径与 paths
筛选器中的模式匹配,则工作流将运行。 例如,只要推送 JavaScript 文件 (.js
),就会运行以下工作流。
on:
push:
paths:
- '**.js'
如果因路径筛选、分支筛选或提交消息而跳过某工作流,则与该工作流关联的检查将保持为“挂起”状态。 要求这些检查成功的拉取请求将被阻止合并。
示例:排除路径
当所有路径名称匹配 paths-ignore
中的模式时,工作流不会运行。 如果任何路径名与 paths-ignore
中的模式不匹配,即使某些路径名与模式匹配,工作流也会运行。
具有以下路径筛选器的工作流将仅在 push
事件上运行,这些事件包括至少一个位于存储库根目录的 docs
目录外的文件。
on:
push:
paths-ignore:
- 'docs/**'
示例:包括和排除路径
不能在单个工作流中使用 paths
和 paths-ignore
筛选同一事件。 如果要同时包括和排除单个事件的路径模式,请使用前缀为 !
字符的 paths
筛选器来指示应排除哪些路径。
如果使用 !
字符定义路径,则还必须定义至少一个不带 !
字符的路径。 如果只想排除路径,请改用 paths-ignore
。
您定义 paths
模式事项的顺序:
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除路径。 - 否定匹配后的匹配肯定模式将再次包含路径。
只要 push
事件包括 sub-project
目录或其子目录中的文件,此示例就会运行,除非该文件在 sub-project/docs
目录中。 例如,更改了 sub-project/index.js
或 sub-project/src/index.js
的推送将会触发工作流运行,但只更改 sub-project/docs/readme.md
的推送不会触发。
on:
push:
paths:
- 'sub-project/**'
- '!sub-project/docs/**'
Git 差异比较
Note
如果推送超过 1,000 项提交,或者如果 GitHub 因超时未生成差异,则工作流将始终运行。
筛选器通过评估更改的文件并针对 paths-ignore
或 paths
列表运行它们来确定是否应运行工作流。 如果没有更改文件,工作流程将不会运行。
GitHub 会针对推送使用双点差异,针对拉取请求使用三点差异,生成已更改文件列表:
- 拉取请求: 三点差异比较主题分支的最近版本与其中使用基本分支最新同步主题分支的提交。
- 推送到现有分支: 双点差异直接相互比较头部和基础 SHA。
- 推送到新分支: 根据已推送最深提交的上级父项的两点差异。
差异限制为 300 个文件。 如果更改的文件与过滤器返回的前 300 个文件不匹配,工作流程将不会运行。 您可能需要创建更多的特定过滤器,以便工作流程自动运行。
有关详细信息,请参阅“关于比较拉取请求中的分支”。
使用筛选器定位工作流程运行事件的特定分支
使用 workflow_run
事件时,可以指定触发工作流必须在哪些分支上运行才能触发工作流。
branches
和 branches-ignore
筛选器接受使用 *
、**
、+
、?
和 !
等字符匹配多个分支名称的 glob 模式。 如果名称包含其中任一字符,而你想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的详细信息,请参阅“GitHub Actions 的工作流语法”。
例如,仅当名为 Build
的工作流在名称以 releases/
开头的分支上运行时,具有以下触发器的工作流才会运行:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
仅当名为 Build
的工作流不在名为 canary
的分支上运行时,具有以下触发器的工作流才会运行:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
不能对工作流中的同一事件同时使用 branches
和 branches-ignore
筛选器。 如果要同时包括和排除单个事件的分支模式,请使用 branches
筛选器以及 !
字符来指示应排除哪些分支。
您定义模式事项的顺序。
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除分支。 - 否定匹配后的匹配肯定模式将再次包含分支。
例如,当名为 Build
的工作流在名为 releases/10
或 releases/beta/mona
但不在名为 releases/10-alpha
、releases/beta/3-alpha
或 main
的分支上运行时,具有以下触发器的工作流将运行。
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
定义手动触发的工作流程的输入
使用 workflow_dispatch
事件时,你可以选择性指定传递到工作流的输入。
此触发器仅当工作流文件位于默认分支时接收事件。
触发的工作流在 inputs
上下文中接收输入。 有关详细信息,请参阅“上下文。”
注释:
- 工作流还将接收
github.event.inputs
上下文中的输入。inputs
上下文和github.event.inputs
上下文中的信息完全相同,但inputs
上下文将布尔值保留为布尔值,而不是将它们转换为字符串。choice
类型解析为字符串,是单个可选选项。 inputs
的顶级属性的最大数目为 10。inputs
的最大有效负载为 65,535 个字符。
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
type: choice
options:
- info
- warning
- debug
print_tags:
description: 'True to print to STDOUT'
required: true
type: boolean
tags:
description: 'Test scenario tags'
required: true
type: string
environment:
description: 'Environment to run tests against'
type: environment
required: true
jobs:
print-tag:
runs-on: ubuntu-latest
if: ${{ inputs.print_tags }}
steps:
- name: Print the input tag to STDOUT
run: echo The tags are ${{ inputs.tags }}
定义可重复使用的工作流程的输入、输出和机密
您可以定义可重用工作流程应从调用工作流程接收的输入和机密。 您还可以指定可重用工作流程将提供给调用工作流程的输出。 有关详细信息,请参阅“重新使用工作流”。
使用事件信息
有关触发工作流运行的事件的信息可在 github.event
上下文中找到。 上下文中的 github.event
属性取决于触发工作流的事件的类型。 例如,在标记议题时触发的工作流程将包含有关议题和标签的信息。
查看事件的所有属性
有关常见属性和示例负载,请参阅 web 挂钩事件文档。 有关详细信息,请参阅“Webhook 事件和有效负载”。
你还可以将整个 github.event
上下文打印出来,以查看哪些属性可用于触发工作流的事件:
jobs:
print_context:
runs-on: ubuntu-latest
steps:
- env:
EVENT_CONTEXT: ${{ toJSON(github.event) }}
run: |
echo $EVENT_CONTEXT
访问和使用事件属性
你可以在工作流中使用 github.event
上下文。 例如,以下工作流在打开更改 package*.json
、.github/CODEOWNERS
或 .github/workflows/**
的拉取请求时运行。 如果拉取请求作者 (github.event.pull_request.user.login
) 不是 octobot
或 dependabot[bot]
,则工作流使用 GitHub CLI 来标记和注释拉取请求 (github.event.pull_request.number
)。
on:
pull_request:
types:
- opened
paths:
- '.github/workflows/**'
- '.github/CODEOWNERS'
- 'package*.json'
jobs:
triage:
if: >-
github.event.pull_request.user.login != 'octobot' &&
github.event.pull_request.user.login != 'dependabot[bot]'
runs-on: ubuntu-latest
steps:
- name: "Comment about changes we can't accept"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR: ${{ github.event.pull_request.html_url }}
run: |
gh pr edit $PR --add-label 'invalid'
gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.'
有关上下文的详细信息,请参阅“访问有关工作流运行的上下文信息”。 有关事件负载的详细信息,请参阅“Webhook 事件和有效负载”。
进一步控制工作流程的运行方式
如果需要比事件、事件活动类型或事件筛选器更精细的控制,则可以使用条件和环境来控制工作流中的单个作业或步骤是否运行。
使用条件
您可以使用条件进一步控制工作流程中的作业或步骤是否运行。
在事件负载中使用值的示例
例如,如果希望在向问题添加特定标签时运行工作流,则可以在 issues labeled
事件活动类型上触发,并使用条件来检查触发工作流的标签。 将任何标签添加到工作流的存储库中的问题时,将运行以下工作流,但仅当标签命名为 bug
时,才会执行 run_if_label_matches
作业。
on:
issues:
types:
- labeled
jobs:
run_if_label_matches:
if: github.event.label.name == 'bug'
runs-on: ubuntu-latest
steps:
- run: echo 'The label was bug'
使用事件类型的示例
例如,如果要根据触发工作流程的事件运行不同的作业或步骤,则可以使用条件来检查事件上下文中是否存在特定的事件类型。 每当议题或拉取请求关闭时,将运行以下工作流程。 如果工作流因问题已关闭而运行,则 github.event
上下文将包含 issue
的值,但不包含 pull_request
的值。 因此,if_issue
步骤将运行,但 if_pr
步骤不会运行。 相反,如果工作流因拉取请求关闭而运行,则 if_pr
步骤将运行,但 if_issue
步骤不会运行。
on:
issues:
types:
- closed
pull_request:
types:
- closed
jobs:
state_event_type:
runs-on: ubuntu-latest
steps:
- name: if_issue
if: github.event.issue
run: |
echo An issue was closed
- name: if_pr
if: github.event.pull_request
run: |
echo A pull request was closed
有关事件上下文中可用信息的详细信息,请参阅“使用事件信息”。 有关如何使用条件的详细信息,请参阅“对工作流和操作中的表达式求值”。
使用环境手动触发工作流程作业
如果要手动触发工作流程中的特定作业,可以使用需要特定团队或用户批准的环境。 首先,使用所需的审阅者配置环境。 有关详细信息,请参阅“管理部署环境”。 然后,使用environment:
键在工作流的作业中引用环境名称。 在至少有一个审阅者批准该作业之前,引用环境的任何作业都不会运行。
例如,只要有推送到 main 分支,以下工作流程就会运行。 build
作业将始终运行。 只有在 build
作业成功完成(由于 needs: [build]
)并且称为 production
的环境的所有规则(包括必需的审阅者)通过(由于 environment: production
)之后,publish
作业才会运行。
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: build
echo 'building'
publish:
needs: [build]
runs-on: ubuntu-latest
environment: production
steps:
- name: publish
echo 'publishing'
所有现行 GitHub 计划的公共存储库中都提供环境、环境机密和部署保护规则。 旧版计划(如 Bronze、Silver 或 Gold)中不提供这些内容。 要访问专用存储库或内部存储库中的环境、环境机密和部署分支,必须使用 GitHub Pro、GitHub Team 或 GitHub Enterprise 。 如果使用的是 GitHub Free、GitHub Pro 或 GitHub Team 计划,则其他部署保护规则(如等待计时器或需要审阅者)仅在公共存储库中提供。
可用事件
有关可用事件的完整列表,请参阅“触发工作流的事件”。