注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
关于工作流程的 YAML 语法
工作流程文件使用 YAML 语法,必须有 .yml
或 .yaml
文件扩展名。 如果您是 YAML 的新用户并想要了解更多信息,请参阅“Y 分钟了解 YAML”。
必须将工作流程文件存储在仓库的 .github/workflows
目录中。
name
工作流程的名称。 GitHub 在仓库的操作页面上显示工作流程的名称。 如果省略 name
,GitHub 将其设置为相对于仓库根目录的工作流程文件路径。
on
要自动触发工作流程,请使用 on
定义哪些事件可以导致工作流程运行。 有关可用事件的列表,请参阅“触发工作流程的事件”。
您可以定义可以触发工作流程的单个或多个事件,或设置时间表。 您还可以将工作流程的执行限于仅针对特定文件、标记或分支更改执行。 以下各节介绍了这些选项。
使用单个事件
例如,推送到工作流程存储库中的任何分支时,将运行具有以下 on
值的工作流程:
on: push
使用多个事件
您可以指定单个事件或多个事件。 例如,当向存储库中的任何分支进行推送或有人复刻存储库时,将运行具有以下 on
值的工作流程:
on: [push, fork]
如果指定多个事件,则只需发生其中一个事件即可触发工作流程。 如果工作流程的多个触发事件同时发生,则将触发多个工作流程运行。
使用活动类型
某些事件具有活动类型,可让您更好地控制工作流程应何时运行。 使用 on.<event_name>.types
定义将触发工作流程运行的事件活动类型。
例如,issue_comment
事件具有 created
、edited
和 deleted
活动类型。 如果您的工作流程在发生 label
事件时触发,则每当创建、编辑或删除标签时,该工作流程都会运行。 如果为 label
事件指定 created
活动类型,则工作流程将在创建标签时运行,但在编辑或删除标签时不会运行。
on:
label:
types:
- created
如果指定多个活动类型,则只需发生其中一个事件活动类型即可触发工作流程。 如果工作流程的多个触发事件活动类型同时发生,则将触发多个工作流程运行。 例如,在打开或标记议题时会触发以下工作流程。 如果打开了具有两个标签的议题,则将启动三个工作流程运行:一个用于议题打开的事件,两个用于两个标记为议题的事件。
on:
issues:
types:
- opened
- labeled
有关每个事件及其活动类型的更多信息,请参阅“触发工作流程的事件”。
使用筛选器
某些事件具有筛选器,可让您更好地控制工作流程应何时运行。
例如,push
事件具有 branches
筛选器,仅当推送到与筛选器 branches
匹配的分支时(而不是在发生任何推送时),工作流程才会运行。
on:
push:
branches:
- main
- 'releases/**'
将活动类型和筛选器用于多个事件
如果为事件指定活动类型或筛选器,并且工作流程触发多个事件,则必须单独配置每个事件。 您必须为所有事件附加冒号 (:
),包括没有配置的事件。
例如,使用以下 on
值的工作流程将在以下情况下运行:
- 创建标签
- 推送到存储库中的
main
分支 - 推送到启用了 GitHub Pages 的分支
on:
label:
types:
- created
push:
branches:
- main
page_build:
on.<event_name>.types
使用 on.<event_name>.types
定义将触发工作流程运行的活动类型。 大多数 GitHub 事件由多种活动触发。 例如,label
在标签 created
、edited
或 deleted
时触发。 通过 types
关键词可缩小触发工作流程运行的活动类型的范围。 如果只有一种活动类型可触发 web 挂钩事件,就没有必要使用 types
关键词。
您可以使用事件 types
的数组。 有关每个事件及其活动类型的更多信息,请参阅“触发工作流程的事件”。
on:
label:
types: [created, edited]
on.<pull_request|pull_request_target>.<branches|branches-ignore>
使用 pull_request
和 pull_request_target
事件时,可以将工作流程配置为仅针对面向特定分支的拉取请求运行。
如果要包括分支名称模式,或者要同时包含和排除分支名称模式,请使用 branches
筛选器。 只需要排除分支名称模式时,请使用 branches-ignore
过滤器。 不能同时对工作流程中的同一事件使用 branches
和 branches-ignore
筛选器。
如果同时定义 branches
/branches-ignore
和 paths
,则工作流程仅在同时满足两个筛选器时才会运行。
branches
和 branches-ignore
关键词接受使用 *
、**
、+
、?
、!
等字符的 glob 模式来匹配多个分支名称。 如果名称包含其中任一字符,而您想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。
示例:包括分支
在 branches
中定义的模式根据 Git ref 的名称进行评估。 例如,每当存在针对拉取请求目标的 pull_request
事件时,就会运行以下工作流程:
- 名为
main
的分支 (refs/heads/main
) - 名为
mona/octocat
的分支 (refs/heads/mona/octocat
) - 名称以
releases/
开头的分支,如releases/10
(refs/heads/releases/10
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
示例:排除分支
当模式与 branches-ignore
模式匹配时,工作流程不会运行。 在 branches
中定义的模式根据 Git ref 的名称进行评估。 例如,每当存在 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
筛选器与 !
字符指示应排除哪些分支。
如果使用 !
字符定义分支,还必须定义至少一个不带 !
字符的分支。 如果只想排除分支,请改用 paths-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'
on.push.<branches|tags|branches-ignore|tags-ignore>
使用 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
,则工作流程仅在同时满足两个筛选器时才会运行。
branches
、branches-ignore
、tags
和 tags-ignore
关键词接受使用 *
、**
、+
、?
、!
等字符匹配多个分支或标记名称的 glob 模式。 如果名称包含其中任一字符,而您想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。
示例:包括分支和标记
在 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
or tags-ignore
模式匹配时,工作流程不会运行。 在 branches
和 tags
中定义的模式根据 Git ref 的名称进行评估。 例如,每当存在 push
事件时,都会运行以下工作流程,除非 push
事件是:
- 名为
mona/octocat
的分支 (refs/heads/mona/octocat
) - 名称与
releases/**-alpha
匹配的分支,如beta/3-alpha
(refs/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
筛选器与 !
字符指示应排除哪些分支或标记。
如果使用 !
字符定义分支,还必须定义至少一个不带 !
字符的分支。 如果只想排除分支,请改用 paths-ignore
。 类似地,如果使用 !
字符定义标记,还必须定义至少一个不带 !
字符的标记。 如果只想排除标记,请改用 paths-ignore
。
您定义模式事项的顺序。
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除 Git 引用。 - 否定匹配后的匹配肯定模式将再次包含 Git 引用。
以下工作流程将在到 releases/10
或 releases/beta/mona
的推送上运行,而不会在到 releases/10-alpha
或 releases/beta/3-alpha
的推送上运行,因为否定模式 !releases/**-alpha
后跟肯定模式。
on:
push:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.<push|pull_request|pull_request_target>.<paths|paths-ignore>
使用 push
和 pull_request
事件时,可以将工作流程配置为根据更改的文件路径运行。 路径过滤器不评估标签的推送。
如果要包括文件路径模式,或者要同时包含和排除文件路径模式,请使用 paths
筛选器。 当您只想排除文件路径模式时,请使用 paths-ignore
筛选器。 不能同时对工作流程中的同一事件使用 paths
and paths-ignore
筛选器。
如果同时定义 branches
/branches-ignore
和 paths
,则工作流程仅在同时满足两个筛选器时才会运行。
paths
和 paths-ignore
关键词接受使用 *
和 **
通配符匹配多个路径名称的 glob 模式。 更多信息请参阅“过滤器模式备忘清单”。
示例:包括路径
如果至少有一个路径与 paths
过滤器中的模式匹配,工作流程将会运行。 例如,以下工作流程将在推送 JavaScript 文件 (.js
) 时运行。
on:
push:
paths:
- '**.js'
注意:如果由于路径过滤、 分支过滤或提交消息而跳过工作流程,则与该工作流程关联的检查将保持“挂起”状态。 需要这些检查成功的拉取请求将被阻止合并。 更多信息请参阅“处理已跳过但必要的检查”。
示例:排除路径
当所有路径名称匹配 paths-ignore
中的模式时,工作流程不会运行。 如果任何路径名与 paths-ignore
中的模式不匹配,则即使某些路径名与模式匹配,工作流程也将运行。
具有以下路径过滤器的工作流程仅在 push
事件上运行,这些事件包括至少一个位于仓库根目录的 docs
目录外的文件。
on:
push:
paths-ignore:
- 'docs/**'
示例:包括和排除路径
不能使用 paths
和 paths-ignore
来筛选单个工作流程中的同一事件。 如果要同时包含和排除单个事件的路径模式,请使用 paths
筛选器与 !
字符指示应排除哪些路径。
如果使用 !
字符定义路径,还必须定义至少一个不带 !
字符的路径。 如果只想排除路径,请改用 paths-ignore
。
您定义模式事项的顺序:
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除路径。 - 否定匹配后的匹配肯定模式将再次包含路径。
只要 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 差异比较
注: 如果您推送超过 1,000 项提交, 或者如果 GitHub 因超时未生成差异,工作流程将始终运行。
过滤器决定是否应通过评估已更改文件,并根据 paths-ignore
or paths
列表运行它们,来运行一个工作流程。 如果没有更改文件,工作流程将不会运行。
GitHub 会针对推送使用双点差异,针对拉取请求使用三点差异,生成已更改文件列表:
- 拉取请求: 三点差异比较主题分支的最近版本与其中使用基本分支最新同步主题分支的提交。
- 推送到现有分支: 双点差异可以直接相互比较头部和基础 SHA。
- 推送到新分支:根据已推送最深提交的前身父项的两点差异。
差异限制为 300 个文件。 如果更改的文件与过滤器返回的前 300 个文件不匹配,工作流程将不会运行。 您可能需要创建更多的特定过滤器,以便工作流程自动运行。
更多信息请参阅“关于比较拉取请求中的分支”。
on.schedule
可以使用 on.schedule
为工作流程定义时间表。 您可以使用 POSIX cron 语法安排工作流程在特定的 UTC 时间运行。 预定的工作流程在默认或基础分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。
此示例在每天 5:30 和 17:30 UTC 触发工作流程:
on:
schedule:
# * is a special character in YAML so you have to quote this string
- cron: '30 5,17 * * *'
单个工作流程可由多个计划
事件触发。 您可以通过 github.event.schedule
上下文访问触发工作流程的计划事件。 本示例触发工作流在每周一至周四的 5:30 UTC 运行,但在星期一和星期三跳过星期一或星期三不运行
步骤。
on:
schedule:
- cron: '30 5 * * 1,3'
- cron: '30 5 * * 2,4'
jobs:
test_schedule:
runs-on: ubuntu-latest
steps:
- name: Not on Monday or Wednesday
if: github.event.schedule != '30 5 * * 1,3'
run: echo "This step will be skipped on Monday and Wednesday"
- name: Every time
run: echo "This step will always run"
有关计划任务语法的更多信息请参阅“触发工作流程的事件”。
on.workflow_run.<branches|branches-ignore>
使用 workflow_run
事件时,可以指定触发工作流程必须在哪些分支上运行才能触发工作流程。
branches
和 branches-ignore
筛选器接受使用 *
、**
、+
、?
、!
等字符的 glob 模式来匹配多个分支名称。 如果名称包含其中任一字符,而您想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。
例如,仅当名为 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'
on.workflow_dispatch.inputs
使用 workflow_dispatch
事件时,您可以选择性指定传递到工作流程的输入。
触发的工作流程接收 github.event.inputs
上下文中的输入。 更多信息请参阅“上下文”。
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
print_tags:
description: 'True to print to STDOUT'
required: true
tags:
description: 'Test scenario tags'
required: true
jobs:
print-tag:
runs-on: ubuntu-latest
if: ${{ github.event.inputs.print_tags == 'true' }}
steps:
- name: Print the input tag to STDOUT
run: echo The tags are ${{ github.event.inputs.tags }}
权限
您可以使用 permissions
修改授予 GITHUB_TOKEN
的默认权限,根据需要添加或删除访问权限,以便仅允许所需的最低访问权限。 更多信息请参阅“工作流程中的身份验证。
您可以使用 permissions
作为顶级密钥,以应用于工作流程中的所有作业,或特定的作业。 当您在特定作业中添加 permissions
键时,该作业中的所有操作和运行命令使用 GITHUB_TOKEN
获取您指定的访问权限。 更多信息请参阅 jobs.<job_id>.permissions
。
可用的作用域和访问权限值:
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
如果您指定其中任何作用域的访问权限,则所有未指定的作用域都被设置为 none
。
您可以使用以下语法来定义所有可用作用域的读取或写入权限:
permissions: read-all|write-all
可以使用以下语法禁用所有可用作用域的权限:
permissions: {}
您可以使用 permissions
键来添加和删除复刻仓库的读取权限,但通常不能授予写入权限。 此行为的例外情况是,管理员在 GitHub Actions 设置中选择了 Send write tokens to workflows from pull requests(从拉取请求发送写入令牌到工作流程)选项。 更多信息请参阅“管理仓库的 GitHub Actions 设置”。
示例:为 GITHUB_TOKEN 分配权限
此示例显示为将要应用到工作流程中所有作业的 GITHUB_TOKEN
设置的权限。 所有权限都被授予读取权限。
name: "My workflow"
on: [ push ]
permissions: read-all
jobs:
...
env
环境变量的 map
可用于工作流程中所有作业的步骤。 您还可以设置仅适用于单个作业的步骤或单个步骤的环境变量。 更多信息请参阅 jobs.<job_id>.env
and jobs.<job_id>.steps[*].env
。
env
映射中的变量不能根据映射中的其他变量进行定义。
当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的环境变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。
示例
env:
SERVER: production
defaults
使用 defaults
创建将应用于工作流程中所有作业的默认设置 map
。 您也可以设置只可用于作业的默认设置。 更多信息请参阅 jobs.<job_id>.defaults
。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
defaults.run
可以使用 defaults.run
为工作流程中的所有 run
步骤提供默认 shell
和 working-directory
选项。 您也可以设置只可用于作业的 run
默认设置。 更多信息请参阅 jobs.<job_id>.defaults.run
。 您不能在此关键词中使用上下文或表达式。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
示例:设置默认 shell 和工作目录
defaults:
run:
shell: bash
working-directory: scripts
concurrency
使用 concurrency
可确保一次只运行一个使用同一并发组的作业或工作流程。 并发组可以是任何字符串或表达式。 表达式只能使用 github
上下文。 有关表达式的详细信息,请参阅“表达式”。
您也可以在作业级别指定 concurrency
。 更多信息请参阅 jobs.<job_id>.concurrency
。
当并发作业或工作流程排队时,如果仓库中使用同一并发组的其他作业或工作流程正在运行,则排队的作业或工作流程将 pending
。 在并发组中任何先前挂起的作业或工作流程都将被取消。 如果还要取消同一并发组中任何当前运行的作业或工作流程,请指定 cancel-in-progress: true
。
示例:使用并发和默认行为
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
示例:使用并发取消任何当前作业或运行
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
示例:使用回退值
如果使用仅为特定事件定义的属性构建组名,则可以使用回退值。 例如,github.head_ref
仅在 pull_request
事件上定义。 如果您的工作流响应除 pull_request
事件之外的其他事件,则需要提供回退以避免语法错误。 以下并发组取消正在进行的作业或仅在 pull_request
事件上运行;如果未定义 github.head_ref
,则并发组将回退到运行 ID,该 ID 保证是唯一的,并且是为运行定义的。
concurrency:
group: ${{ github.head_ref || github.run_id }}
cancel-in-progress: true
示例:仅取消当前工作流程的正在进行的作业或运行
如果同一存储库中有多个工作流程,则并发组名称在工作流程中必须唯一,以避免取消正在进行的作业或从其他工作流程运行。 否则,无论工作流程如何,任何以前正在进行的或挂起的作业都将被取消。
要仅取消同一工作流程的正在进行的运行,可以使用 github.workflow
属性来构建并发组:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs
工作流程运行由一个或多个 jobs
组成,这些作业在默认情况下并行运行。 要按顺序运行作业,您可以使用 <job_id>needs
关键词在其他作业上定义依赖项。
每个作业在 runs-on
指定的运行器环境中运行。
在工作流程的使用限制之内可运行无限数量的作业。 更多信息请参阅 “使用限制和计费”(对于 GitHub 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。
如果需要查找在工作流程运行中运行的作业的唯一标识符,可以使用 GitHub Enterprise Server API。 更多信息请参阅“工作流程作业”。
jobs.<job_id>
使用 jobs.<job_id>
为您的作业提供唯一标识符。 键值 job_id
是一个字符串,其值是作业配置数据的映像。 必须将 <job_id>
替换为 jobs
对象唯一的字符串。 <job_id>
必须以字母或 _
开头,并且只能包含字母数字字符、-
或 _
。
示例:创建作业
在此示例中,已创建两个作业,其 job_id
值为 my_first_job
和 my_second_job
。
jobs:
my_first_job:
name: My first job
my_second_job:
name: My second job
jobs.<job_id>.name
使用 jobs.<job_id>.name
为作业设置名称,该名称显示在 GitHub UI 中。
jobs.<job_id>.permissions
对于特定作业,可以使用 jobs.<job_id>.permissions
修改授予 GITHUB_TOKEN
的默认权限,根据需要添加或删除访问权限,以便仅允许所需的最低访问权限。 更多信息请参阅“工作流程中的身份验证。
通过在工作定义中指定权限,您可以根据需要为每个作业的 GITHUB_TOKEN
配置一组不同的权限。 或者,您也可以为工作流程中的所有作业指定权限。 有关在工作流程级别定义权限的信息,请参阅 permissions
。
可用的作用域和访问权限值:
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
如果您指定其中任何作用域的访问权限,则所有未指定的作用域都被设置为 none
。
您可以使用以下语法来定义所有可用作用域的读取或写入权限:
permissions: read-all|write-all
可以使用以下语法禁用所有可用作用域的权限:
permissions: {}
您可以使用 permissions
键来添加和删除复刻仓库的读取权限,但通常不能授予写入权限。 此行为的例外情况是,管理员在 GitHub Actions 设置中选择了 Send write tokens to workflows from pull requests(从拉取请求发送写入令牌到工作流程)选项。 更多信息请参阅“管理仓库的 GitHub Actions 设置”。
示例:为特定作业设置权限
此示例显示为将要应用到作业 stale
的 GITHUB_TOKEN
设置的权限。 对于 issues
和 pull-requests
拉取请求,授予写入访问权限。 所有其他范围将没有访问权限。
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v4
jobs.<job_id>.needs
使用 jobs.<job_id>.needs
确定必须成功完成才能运行此作业的任何作业。 它可以是一个字符串,也可以是字符串数组。 如果某个作业失败,则所有需要它的作业都会被跳过,除非这些作业使用让该作业继续的条件表达式。 如果运行包含一系列相互需要的作业,则从故障点开始,故障将应用于依赖关系链中的所有作业。
示例:需要成功的依赖作业
jobs:
job1:
job2:
needs: job1
job3:
needs: [job1, job2]
在此示例中,job1
必须在 job2
开始之前成功完成,而 job3
要等待 job1
和 job2
完成。
此示例中的作业按顺序运行:
job1
job2
job3
示例:不需要成功的依赖作业
jobs:
job1:
job2:
needs: job1
job3:
if: ${{ always() }}
needs: [job1, job2]
在此示例中,job3
使用 always()
条件表达式,因此它始终在 job1
和 job2
完成后运行,不管它们是否成功。 更多信息请参阅“表达式”。
jobs.<job_id>.if
您可以使用 jobs.<job_id>.if
条件阻止作业在条件得到满足之前运行。 您可以使用任何支持上下文和表达式来创建条件。
在 if
条件下使用表达式时,可以省略表达式语法 (${{ }}
),因为 GitHub 会自动将 if
条件作为表达式求值。 更多信息请参阅“表达式”。
示例:仅运行特定存储库的作业
此示例使用 if
来控制 production-deploy
作业何时可以运行。 仅当存储库名为 octo-repo-prod
并且位于 octo-org
组织内时,它才会运行。 否则,作业将标记为跳过。
name: example-workflow
on: [push]
jobs:
production-deploy:
if: github.repository == 'octo-org/octo-repo-prod'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: '14'
- run: npm install -g bats
jobs.<job_id>.runs-on
使用 jobs.<job_id>.runs-on
来定义运行作业的计算机类型。 可以将 runs-on
作为单个字符串或字符串数组提供。 如果指定字符串数组,则工作流程将在自托管运行器上运行,其标签与所有指定的 runs-on
值(如果可用)匹配。 如果要在多台计算机上运行工作流程,请使用 jobs.<job_id>.strategy
。
注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
选择 GitHub 托管的运行器
If you use a GitHub-hosted runner, each job runs in a fresh instance of a runner image specified by runs-on
.
可用的 GitHub 托管的运行器类型包括:
Runner image | YAML 工作流程标签 | 注: |
---|---|---|
Windows Server 2022 | windows-latest 或 windows-2022 |
windows-latest 标签目前使用 Windows Server 2022 运行器映像。
|
Windows Server 2019 | windows-2019 |
|
Ubuntu 22.04 | ubuntu-22.04 |
|
Ubuntu 20.04 | ubuntu-latest 或 ubuntu-20.04 |
|
Ubuntu 18.04 [deprecated] | ubuntu-18.04 |
Migrate to ubuntu-20.04 or ubuntu-22.04 . For more information, see this GitHub blog post.
|
macOS Monterey 12 | macos-12 |
|
macOS Big Sur 11 | macos-latest 或 macos-11 |
macos-latest 标签目前使用 macOS 11 运行器映像。
|
macOS Catalina 10.15 [deprecated] | macos-10.15 |
Migrate to macOS-11 or macOS-12 . For more information, see this GitHub blog post.
|
Note: The -latest
runner images are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.
注意: 测试版和已弃用映像均按“原样”、“包含所有故障”和“可用”提供,并且不在服务级别协议和保修范围内。 测试版映像可能不在客户支持范围内。
示例:指定操作系统
runs-on: ubuntu-latest
更多信息请参阅“关于 GitHub 托管的运行器”。
选择自托管的运行器
要为工作指定自托管的运行器,请在工作流程文件中使用自托管运行器标签配置 runs-on
。
所有自托管运行器都有 self-hosted
标签。 仅使用此标签将选择任何自托管运行器。 要选择满足特定条件(如操作系统或体系结构)的运行器,我们建议提供一组标签,这些标签以 self-hosted
开头(必须首先列出),然后根据需要包含其他标签。 指定一系列标签时,作业将在具有指定的所有标签的运行器上排队。
虽然 self-hosted
标签不是必需的,但我们强烈建议在使用自托管运行器时指定它,以确保您的作业不会无意中指定任何当前或将来 GitHub 托管的运行器。
示例:使用标签选择运行器
runs-on: [self-hosted, linux]
更多信息请参阅“关于自托管的运行器”和“在工作流程中使用自托管的运行器”。
jobs.<job_id>.environment
使用 jobs.<job_id>.environment
来定义作业引用的环境。 在将引用环境的作业发送到运行器之前,必须通过所有环境保护规则。 更多信息请参阅“使用环境进行部署”。
您可以将环境仅作为环境 name
,或作为具有 name
和 url
的环境变量。 URL 映射到部署 API 中的 environment_url
。 有关部署 API 的更多信息,请参阅“部署”。
示例:使用单个环境名称
environment: staging_environment
示例:使用环境名称和 URL
environment:
name: production_environment
url: https://github.com
URL 可以是表达式,并且可以使用除 secrets
上下文以外的任何上下文。 有关表达式的详细信息,请参阅“表达式”。
示例:使用输出作为 URL
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.concurrency
注意: 在作业级别指定并发时,无法保证在 5 分钟内排队的作业或运行的互相顺序。
使用 jobs.<job_id>.concurrency
可确保一次只运行一个使用同一并发组的作业或工作流程。 并发组可以是任何字符串或表达式。 表达式可以使用除 secrets
上下文以外的任何上下文。 有关表达式的详细信息,请参阅“表达式”。
您也可以在工作流程级别指定 concurrency
。 更多信息请参阅 concurrency
。
当并发作业或工作流程排队时,如果仓库中使用同一并发组的其他作业或工作流程正在运行,则排队的作业或工作流程将 pending
。 在并发组中任何先前挂起的作业或工作流程都将被取消。 如果还要取消同一并发组中任何当前运行的作业或工作流程,请指定 cancel-in-progress: true
。
示例:使用并发和默认行为
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
示例:使用并发取消任何当前作业或运行
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
示例:使用回退值
如果使用仅为特定事件定义的属性构建组名,则可以使用回退值。 例如,github.head_ref
仅在 pull_request
事件上定义。 如果您的工作流响应除 pull_request
事件之外的其他事件,则需要提供回退以避免语法错误。 以下并发组取消正在进行的作业或仅在 pull_request
事件上运行;如果未定义 github.head_ref
,则并发组将回退到运行 ID,该 ID 保证是唯一的,并且是为运行定义的。
concurrency:
group: ${{ github.head_ref || github.run_id }}
cancel-in-progress: true
示例:仅取消当前工作流程的正在进行的作业或运行
如果同一存储库中有多个工作流程,则并发组名称在工作流程中必须唯一,以避免取消正在进行的作业或从其他工作流程运行。 否则,无论工作流程如何,任何以前正在进行的或挂起的作业都将被取消。
要仅取消同一工作流程的正在进行的运行,可以使用 github.workflow
属性来构建并发组:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs.<job_id>.outputs
您可以使用 jobs.<job_id>.outputs
为作业创建输出 map
。 作业输出可用于所有依赖此作业的下游作业。 有关定义作业依赖项的更多信息,请参阅 jobs.<job_id>.needs
。
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.
当每个作业结束时,在运行器上评估包含表达式的作业输出。 包含密码的输出在运行器上编辑,不会发送至 GitHub Actions。
要在依赖的作业中使用作业输出, 您可以使用 needs
上下文。 更多信息请参阅“上下文”。
示例:定义作业的输出
jobs:
job1:
runs-on: ubuntu-latest
# Map a step output to a job output
outputs:
output1: ${{ steps.step1.outputs.test }}
output2: ${{ steps.step2.outputs.test }}
steps:
- id: step1
run: echo "::set-output name=test::hello"
- id: step2
run: echo "::set-output name=test::world"
job2:
runs-on: ubuntu-latest
needs: job1
steps:
- run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}
jobs.<job_id>.env
环境变量的 map
可用于作业中的所有步骤。 您也可以设置整个工作流程或单个步骤的环境变量。 更多信息请参阅 env
和 jobs.<job_id>.steps[*].env
。
当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的环境变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。
示例
jobs:
job1:
env:
FIRST_NAME: Mona
jobs.<job_id>.defaults
使用 jobs.<job_id>.defaults
创建将应用于作业中所有步骤的默认设置 map
。 您也可以设置整个工作流程的默认设置。 更多信息请参阅 defaults
。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
jobs.<job_id>.defaults.run
使用 jobs.<job_id>.defaults.run
为作业中所有 run
步骤提供默认的 shell
和 working-directory
。 此部分不允许上下文和表达式。
您可以为作业中的所有 run
步骤提供默认的 shell
和 working-directory
选项。 您也可以为整个工作流程设置 run
的默认设置。 更多信息请参阅 jobs.defaults.run
。 您不能在此关键词中使用上下文或表达式。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
示例:为作业设置默认 run
步骤选项
jobs:
job1:
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: scripts
jobs.<job_id>.steps
作业包含一系列任务,称为 steps
。 步骤可以运行命令、运行设置任务,或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。 并非所有步骤都会运行操作,但所有操作都会作为步骤运行。 每个步骤在运行器环境中以其自己的进程运行,且可以访问工作区和文件系统。 因为步骤以自己的进程运行,所以步骤之间不会保留环境变量的更改。 GitHub 提供内置的步骤来设置和完成作业。
在工作流程的使用限制之内可运行无限数量的步骤。 更多信息请参阅 “使用限制和计费”(对于 GitHub 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。
示例
name: Greeting from Mona
on: push
jobs:
my-job:
name: My Job
runs-on: ubuntu-latest
steps:
- name: Print a greeting
env:
MY_VAR: Hi there! My name is
FIRST_NAME: Mona
MIDDLE_NAME: The
LAST_NAME: Octocat
run: |
echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.
jobs.<job_id>.steps[*].id
步骤的唯一标识符。 您可以使用 id
引用上下文中的步骤。 更多信息请参阅“上下文”。
jobs.<job_id>.steps[*].if
您可以使用 if
条件阻止步骤在条件得到满足之前运行。 您可以使用任何支持上下文和表达式来创建条件。
在 if
条件下使用表达式时,可以省略表达式语法 (${{ }}
),因为 GitHub 会自动将 if
条件作为表达式求值。 更多信息请参阅“表达式”。
示例:使用上下文
此步骤仅在事件类型为 pull_request
并且事件操作为 unassigned
时运行。
steps:
- name: My first step
if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
run: echo This event is a pull request that had an assignee removed.
示例:使用状态检查功能
my backup step
仅在作业的上一步失败时运行。 更多信息请参阅“表达式”。
steps:
- name: My first step
uses: octo-org/action-name@main
- name: My backup step
if: ${{ failure() }}
uses: actions/heroku@1.0.0
示例:使用机密
无法直接在 if:
条件中引用机密。 而应考虑将机密设置为作业级环境变量,然后引用环境变量以有条件地运行作业中的步骤。
如果尚未设置机密,则引用该机密的表达式(例如示例中的 ${{ secrets.SuperSecret }}
)的返回值将为空字符串。
name: Run a step if a secret has been set
on: push
jobs:
my-jobname:
runs-on: ubuntu-latest
env:
super_secret: ${{ secrets.SuperSecret }}
steps:
- if: ${{ env.super_secret != '' }}
run: echo 'This step will only run if the secret has a value set.'
- if: ${{ env.super_secret == '' }}
run: echo 'This step will only run if the secret does not have a value set.'
jobs.<job_id>.steps[*].name
步骤显示在 GitHub 上的名称。
jobs.<job_id>.steps[*].uses
选择要作为作业中步骤的一部分运行的操作。 操作是一种可重复使用的代码单位。 您可以使用工作流程所在仓库中、公共仓库中或发布 Docker 容器映像中定义的操作。
强烈建议指定 Git ref、SHA 或 Docker 标记编号来包含所用操作的版本。 如果不指定版本,在操作所有者发布更新时可能会中断您的工作流程或造成非预期的行为。
- 使用已发行操作版本的 SHA 对于稳定性和安全性是最安全的。
- 使用特定主要操作版本可在保持兼容性的同时接收关键修复和安全补丁。 还可确保您的工作流程继续工作。
- 使用操作的默认分支可能很方便,但如果有人新发布具有突破性更改的主要版本,您的工作流程可能会中断。
有些操作要求必须通过 with
关键词设置输入。 请查阅操作的自述文件,确定所需的输入。
操作为 JavaScript 文件或 Docker 容器。 如果您使用的操作是 Docker 容器,则必须在 Linux 环境中运行作业。 更多详情请参阅 runs-on
。
示例:使用版本化操作
steps:
# Reference a specific commit
- uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
# Reference the major version of a release
- uses: actions/checkout@v2
# Reference a specific version
- uses: actions/checkout@v2.2.0
# Reference a branch
- uses: actions/checkout@main
示例:使用公共操作
{owner}/{repo}@{ref}
您可以指定公共 GitHub 仓库中的分支、引用或 SHA。
jobs:
my_first_job:
steps:
- name: My first step
# Uses the default branch of a public repository
uses: actions/heroku@main
- name: My second step
# Uses a specific version tag of a public repository
uses: actions/aws@v2.0.1
示例:在子目录中使用公共操作
{owner}/{repo}/{path}@{ref}
公共 GitHub 仓库中特定分支、引用或 SHA 上的子目录。
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/aws/ec2@main
示例:使用工作流程所在仓库中操作
./path/to/dir
包含工作流程的仓库中操作的目录路径。 在使用操作之前,必须检出仓库。
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v2
- name: Use local my-action
uses: ./.github/actions/my-action
示例:使用 Docker 中枢操作
docker://{image}:{tag}
Docker 中枢上发布的 Docker 映像。
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://alpine:3.8
示例:使用 Docker 公共注册表操作
docker://{host}/{image}:{tag}
公共注册表中的 Docker 映像。 此示例在 gcr.io
使用 Google Container Registry。
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://gcr.io/cloud-builders/gradle
示例:在不同于工作流程的私有仓库中使用操作
您的工作流程必须检出私有仓库,并在本地引用操作。 生成个人访问令牌并将该令牌添加为加密密钥。 更多信息请参阅“创建个人访问令牌”和“加密密码”。
将示例中的 PERSONAL_ACCESS_TOKEN
替换为您的密钥名称。
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v2
with:
repository: octocat/my-private-repo
ref: v1.0
token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
path: ./.github/actions/my-private-repo
- name: Run my action
uses: ./.github/actions/my-private-repo/my-action
jobs.<job_id>.steps[*].run
使用操作系统 shell 运行命令行程序。 如果不提供 name
,步骤名称将默认为 run
命令中指定的文本。
命令默认使用非登录 shell 运行。 您可以选择不同的 shell,也可以自定义用于运行命令的 shell。 更多信息请参阅 jobs.<job_id>.steps[*].shell
。
每个 run
关键词代表运行器环境中一个新的进程和 shell。 当您提供多行命令时,每行都在同一个 shell 中运行。 例如:
-
单行命令:
- name: Install Dependencies run: npm install
-
多行命令:
- name: Clean install dependencies and build run: | npm ci npm run build
使用 working-directory
关键词,您可以指定运行命令的工作目录位置。
- name: Clean temp directory
run: rm -rf *
working-directory: ./temp
jobs.<job_id>.steps[*].shell
您可以使用 shell
关键词覆盖运行器操作系统中默认的 shell 设置。 您可以使用内置的 shell
关键词,也可以自定义 shell 选项集。 内部运行的 shell 命令执行一个临时文件,其中包含 run
关键词中指定的命令。
支持的平台 | shell 参数 | 描述 | 内部运行命令 |
---|---|---|---|
Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when bash is specified explicitly. If bash is not found in the path, this is treated as sh . | bash -e {0} |
所有 | bash | 非 Windows 平台上回退到 sh 的默认 shell。 指定 Windows 上的 bash shell 时,将使用 Git for Windows 随附的 bash shel。 | bash --noprofile --norc -eo pipefail {0} |
所有 | pwsh | PowerShell Core。 GitHub 将扩展名 .ps1 附加到您的脚本名称。 | pwsh -command ". '{0}'" |
所有 | python | 执行 python 命令。 | python {0} |
Linux / macOS | sh | 未提供 shell 且 在路径中找不到 bash 时的非 Windows 平台的后退行为。 | sh -e {0} |
Windows | cmd | GitHub 将扩展名 .cmd 附加到您的脚本名称并替换 {0} 。 | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | 这是 Windows 上使用的默认 shell。 PowerShell Core。 GitHub 将扩展名 .ps1 附加到您的脚本名称。 如果自托管的 Windows 运行器没有安装 PowerShell Core,则使用 PowerShell Desktop 代替。 | pwsh -command ". '{0}'" . |
Windows | powershell | PowerShell 桌面。 GitHub 将扩展名 .ps1 附加到您的脚本名称。 | powershell -command ". '{0}'" . |
示例:使用 bash 运行脚本
steps:
- name: Display the path
run: echo $PATH
shell: bash
示例:使用 Windows cmd
运行脚本
steps:
- name: Display the path
run: echo %PATH%
shell: cmd
示例:使用 PowerShell Core 运行脚本
steps:
- name: Display the path
run: echo ${env:PATH}
shell: pwsh
示例:使用 PowerShell 桌面运行脚本
steps:
- name: Display the path
run: echo ${env:PATH}
shell: powershell
示例:运行 python 脚本
steps:
- name: Display the path
run: |
import os
print(os.environ['PATH'])
shell: python
自定义 shell
您可以使用 command […options] {0} [..more_options]
将 shell
值设置为模板字符串。 GitHub 将字符串的第一个用空格分隔的词解释为命令,并在 {0}
处插入临时脚本的文件名。
例如:
steps:
- name: Display the environment variables and their values
run: |
print %ENV
shell: perl {0}
此示例中使用的命令 perl
必须安装在运行器上。
退出代码和错误操作首选项
至于内置的 shell 关键词,我们提供由 GitHub 托管运行程序执行的以下默认值。 在运行 shell 脚本时,您应该使用这些指南。
-
bash
/sh
:- 使用
set -eo pipefail
的快速失败行为:在显式指定shell: bash
时设置此选项。 默认情况下不应用。 - 您可以通过向 shell 选项提供模板字符串来完全控制 shell 参数。 例如
bash {0}
。 - sh 类 shell 使用脚本中最后执行的命令的退出代码退出,也是操作的默认行为。 运行程序将根据此退出代码将步骤的状态报告为失败/成功。
- 使用
-
powershell
/pwsh
- 可能时的快速失败行为。 对于
pwsh
和powershell
内置 shell,我们将$ErrorActionPreference = 'stop'
附加到脚本内容。 - 我们将
if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }
附加到 powershell 脚本,以使操作状态反映脚本的最后一个退出代码。 - 用户可随时通过不使用内置 shell 并提供类似如下的自定义 shell 选项来退出:
pwsh -File {0}
或powershell -Command "& '{0}'"
,具体取决于需求。
- 可能时的快速失败行为。 对于
-
cmd
- 除了编写脚本来检查每个错误代码并相应地响应之外,似乎没有办法完全选择快速失败行为。 由于我们默认不能实际提供该行为,因此您需要将此行为写入脚本。
cmd.exe
在退出时带有其执行的最后一个程序的错误等级,并且会将错误代码返回到运行程序。 此行为在内部与上一个sh
和pwsh
默认行为一致,是cmd.exe
的默认值,所以此行为保持不变。
jobs.<job_id>.steps[*].with
输入参数的 map
由操作定义。 每个输入参数都是一个键/值对。 输入参数被设置为环境变量。 该变量的前缀为 INPUT_
,并转换为大写。
示例
定义 hello_world
操作所定义的三个输入参数(first_name
、middle_name
和 last_name
)。 这些输入变量将被 hello-world
操作作为 INPUT_FIRST_NAME
、INPUT_MIDDLE_NAME
和 INPUT_LAST_NAME
环境变量使用。
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/hello_world@main
with:
first_name: Mona
middle_name: The
last_name: Octocat
jobs.<job_id>.steps[*].with.args
string
定义 Docker 容器的输入。 GitHub 在容器启动时将 args
传递到容器的 ENTRYPOINT
。 此参数不支持 array of strings
。
示例
steps:
- name: Explain why this job ran
uses: octo-org/action-name@main
with:
entrypoint: /bin/echo
args: The ${{ github.event_name }} event triggered this step.
args
用来代替 Dockerfile
中的 CMD
指令。 如果在 Dockerfile
中使用 CMD
,请遵循按偏好顺序排序的指导方针:
- 在操作的自述文件中记录必要的参数,并在
CMD
指令的中忽略它们。 - 使用默认值,允许不指定任何
args
即可使用操作。 - 如果操作显示
--help
标记或类似项,请将其用作默认值,以便操作自行记录。
jobs.<job_id>.steps[*].with.entrypoint
覆盖 Dockerfile
中的 Docker ENTRYPOINT
,或在未指定时设置它。 与包含 shell 和 exec 表单的 Docker ENTRYPOINT
指令不同,entrypoint
关键词只接受定义要运行的可执行文件的单个字符串。
示例
steps:
- name: Run a custom command
uses: octo-org/action-name@main
with:
entrypoint: /a/different/executable
entrypoint
关键词旨在用于 Docker 容器操作,但您也可以将其用于未定义任何输入的 JavaScript 操作。
jobs.<job_id>.steps[*].env
设置供步骤用于运行器环境的环境变量。 您也可以设置整个工作流程或某个作业的环境变量。 更多信息请参阅 env
和 jobs.<job_id>.env
。
当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的环境变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。
公共操作可在自述文件中指定预期的环境变量。 如果要在环境变量中设置密码,必须使用 secrets
上下文进行设置。 更多信息请参阅“使用环境变量”和“上下文”。
示例
steps:
- name: My first action
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FIRST_NAME: Mona
LAST_NAME: Octocat
jobs.<job_id>.steps[*].continue-on-error
防止步骤失败时作业也会失败。 设置为 true
以允许在此步骤失败时作业能够通过。
jobs.<job_id>.steps[*].timeout-minutes
终止进程之前运行该步骤的最大分钟数。
jobs.<job_id>.timeout-minutes
在 GitHub 自动取消运行之前可让作业运行的最大分钟数。 默认值:360
如果超时超过运行器的作业执行时限,作业将在达到执行时限时取消。 有关作业执行时间限制的更多信息,请参阅 “使用限制和计费”(对于 GitHub 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。
注意: GITHUB_TOKEN
在作业完成时或最多 24 小时后过期。 对于自托管运行器,如果作业超时大于 24 小时,则令牌可能是限制因素。 有关 GITHUB_TOKEN
的更多信息,请参阅“关于 GITHUB_TOKEN
机密”。
jobs.<job_id>.strategy
使用 jobs.<job_id>.strategy
为您的任务使用矩阵策略。 A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables. 例如,可以使用矩阵策略在一种语言的多个版本或多个操作系统上测试代码。 更多信息请参阅“对作业使用矩阵”。
jobs.<job_id>.strategy.matrix
使用 jobs.<job_id>.strategy.matrix
定义不同作业配置的矩阵。 在矩阵中,定义一个或多个变量,后跟一个值数组。 例如,以下矩阵有一个名为 version
的变量,其值为 [10, 12, 14]
,以及一个名为 os
的变量,其值为 [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
将为每个可能的变量组合运行一个作业。 在此示例中,工作流程将运行六个作业,每个作业对应于 os
和 version
变量的组合。
默认情况下,GitHub Enterprise Server 将根据运行器的可用性最大化并行运行的作业数。 矩阵中变量的顺序决定了作业的创建顺序。 您定义的第一个变量将是工作流程运行中创建的第一个作业。 例如,上面的矩阵将按以下顺序创建作业:
{version: 10, os: ubuntu-latest}
{version: 10, os: windows-latest}
{version: 12, os: ubuntu-latest}
{version: 12, os: windows-latest}
{version: 14, os: ubuntu-latest}
{version: 14, os: windows-latest}
矩阵将为每个工作流运行生成最多 256 个作业。 此限制适用于 GitHub Enterprise Server 托管和自托管运行器。
您定义的变量将成为 matrix
上下文中的属性,您可以在工作流程文件的其他区域中引用该属性。 在此示例中,可以使用 matrix.version
和 matrix.os
来访问作业所用 version
和 os
的当前值。 更多信息请参阅“上下文”。
示例:使用单维矩阵
可以指定单个变量来创建单维矩阵。
例如,以下工作流程使用值 [10, 12, 14]
定义变量 version
。 工作流程将运行三个作业,变量中的每个值对应一个作业。 每个作业将通过 matrix.version
上下文访问 version
值,并将该值作为 node-version
传递给 actions/setup-node
操作。
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
示例:使用多维矩阵
您可以指定多个变量来创建多维矩阵。 将为每个可能的变量组合运行一个作业。
例如,以下工作流程指定了两个变量:
os
变量中指定的两个操作系统- 在
version
变量中指定的三个 Node.js 版本
工作流程将运行六个作业,每个作业对应于 os
和 version
变量的组合。 每个作业都会将 runs-on
值设置为当前 os
值,并将当前 version
值传递给 actions/setup-node
操作。
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-22.04, ubuntu-20.04]
version: [10, 12, 14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
示例:使用上下文创建矩阵
您可以使用上下文来创建矩阵。 有关上下文的更多信息,请参阅“上下文”。
例如,以下工作流程在发生 repository_dispatch
事件时触发,并使用事件负载中的信息来生成矩阵。 使用如下所示的有效负载创建存储库调度事件时,矩阵 version
变量的值将为 [12, 14, 16]
。 有关 repository_dispatch
触发器的更多信息,请参阅“触发工作流程的事件”。
{
"event_type": "test",
"client_payload": {
"versions": [12, 14, 16]
}
}
on:
repository_dispatch:
types:
- test
jobs:
example_matrix:
runs-on: ubuntu-latest
strategy:
matrix:
version: ${{ github.event.client_payload.versions }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
jobs.<job_id>.strategy.matrix.include
使用 jobs.<job_id>.strategy.matrix.include
扩展现有矩阵配置或添加新配置。 include
的值是对象的列表。
对于 include
列表中的每个对象,如果没有键:值对覆盖任何原始矩阵值,则该对象中的键:值对将添加到每个矩阵组合中。 如果无法将对象添加到任何矩阵组合中,则将改为创建新的矩阵组合。 请注意,原始矩阵值不会被覆盖,但添加的矩阵值可能会被覆盖。
例如,此矩阵:
strategy:
matrix:
fruit: [apple, pear]
animal: [cat, dog]
include:
- color: green
- color: pink
animal: cat
- fruit: apple
shape: circle
- fruit: banana
- fruit: banana
animal: cat
将产生六个具有以下矩阵组合的作业:
{fruit: apple, animal: cat, color: pink, shape: circle}
{fruit: apple, animal: dog, color: green, shape: circle}
{fruit: pear, animal: cat, color: pink}
{fruit: pear, animal: dog, color: green}
{fruit: banana}
{fruit: banana, animal: cat}
遵循以下逻辑:
{color: green}
将添加到所有原始矩阵组合中,因为它可以在不覆盖原始组合的任何部分的情况下添加。{color: pink, animal: cat}
仅将color:pink
添加到包含animal: cat
的原始矩阵组合中。 这将覆盖由上一个include
条目添加的color: green
。{fruit: apple, shape: circle}
仅将shape: circle
仅添加到包含fruit: apple
的原始矩阵组合。{fruit: banana}
不能在不覆盖值的情况下添加到任何原始矩阵组合中,因此将其添加为附加矩阵组合。{fruit: banana, animal: cat}
不能在不覆盖值的情况下添加到任何原始矩阵组合中,因此将其添加为附加矩阵组合。 它不会添加到{fruit: banana}
矩阵组合中,因为该组合不是原始矩阵组合之一。
示例:展开配置
例如,以下工作流程将运行六个作业,每个作业对应于 os
和 node
的组合。 当 windows-latest
值为 os
且 16
值为 node
的作业运行时,作业中将包含一个名为 npm
、值为 6
的附加变量。
jobs:
example_matrix:
strategy:
matrix:
os: [windows-latest, ubuntu-latest]
node: [12, 14, 16]
include:
- os: windows-latest
node: 16
npm: 6
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node }}
- if: ${{ matrix.npm }}
run: npm install -g npm@${{ matrix.npm }}
- run: npm --version
示例:添加配置
例如,此矩阵将运行 10 个作业,矩阵中 os
和 version
的每个组合各一个作业,再加上一个 windows-latest
值为 os
且 17
值为 version
的作业。
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
如果未指定任何矩阵变量,则 include
下的所有配置都将运行。 例如,以下工作流程将运行两个作业,每个作业一个 include
条目。 这使您可以利用矩阵策略,而无需完全填充的矩阵。
jobs:
includes_only:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- site: "production"
datacenter: "site-a"
- site: "staging"
datacenter: "site-b"
jobs.<job_id>.strategy.matrix.exclude
若要删除矩阵中定义的特定配置,请使用 jobs.<job_id>.strategy.matrix.exclude
。 排除的配置只需是部分匹配即可排除。 例如,以下工作流程将运行 9 个作业:12 个配置中每个配置一个作业,减去与 {os: macos-latest, version: 12, environment: production}
匹配的一个已排除作业,以及与 {os: windows-latest, version: 16}
匹配的两个已排除作业。
strategy:
matrix:
os: [macos-latest, windows-latest]
version: [12, 14, 16]
environment: [staging, production]
exclude:
- os: macos-latest
version: 12
environment: production
- os: windows-latest
version: 16
runs-on: ${{ matrix.os }}
注意:所有 include
组合在 exclude
后处理。 这允许您使用 include
添加回以前排除的组合。
jobs.<job_id>.strategy.fail-fast
您可以使用 jobs.<job_id>.strategy.fail-fast
and jobs.<job_id>.continue-on-error
控制如何处理作业失败。
jobs.<job_id>.strategy.fail-fast
适用于整个矩阵。 如果jobs.<job_id>.strategy.fail-fast
设置为 true
,如果矩阵中的任何作业失败, GitHub Enterprise Server 将取消矩阵中所有正在进行的作业和排队的作业。 此属性默认为 true
。
jobs.<job_id>.continue-on-error
适用于单个作业。 如果 jobs.<job_id>.continue-on-error
为 true
,则矩阵中的其他作业将继续运行,即使具有 jobs.<job_id>.continue-on-error: true
的作业失败也一样。
您可以同时使用 jobs.<job_id>.strategy.fail-fast
和 jobs.<job_id>.continue-on-error
。 例如,以下工作流程将启动四个作业。 对于每个作业,continue-on-error
由 matrix.experimental
的值确定。 如果任何具有 continue-on-error: false
的作业失败,则将取消所有正在进行的作业或排队的作业。 如果具有 continue-on-error: true
的作业失败,其他作业将不受影响。
jobs:
test:
runs-on: ubuntu-latest
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: true
matrix:
version: [6, 7, 8]
experimental: [false]
include:
- version: 9
experimental: true
jobs.<job_id>.strategy.max-parallel
默认情况下,GitHub Enterprise Server 将根据运行器的可用性最大化并行运行的作业数。 要设置在使用 matrix
作业策略时可以同时运行的最大作业数,请使用 jobs.<job_id>.strategy.max-parallel
。
例如,以下工作流程一次最多运行两个作业,即使有运行器可以同时运行所有六个作业也是如此。
jobs:
example_matrix:
strategy:
max-parallel: 2
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
jobs.<job_id>.continue-on-error
防止工作流程运行在作业失败时失败。 设置为 true
以允许工作流程运行在此作业失败时通过。
示例:防止特定失败的矩阵作业无法运行工作流程
您可以允许作业矩阵中的特定任务失败,但工作流程运行不失败。 例如, 只允许 node
设置为 15
的实验性作业失败,而不允许工作流程运行失败。
runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: false
matrix:
node: [13, 14]
os: [macos-latest, ubuntu-latest]
experimental: [false]
include:
- node: 15
os: ubuntu-latest
experimental: true
jobs.<job_id>.container
注:如果您的工作流程使用 Docker 容器操作、作业容器或服务容器,则必须使用 Linux 运行器:
- 如果您要使用 GitHub 托管的运行器,则必须使用 Ubuntu 运行器。
- 如果您要使用自托管运行器,则必须使用 Linux 机器作为运行器,并且必须安装 Docker。
使用 jobs.<job_id>.container
创建一个容器,以在尚未指定容器的作业中运行任何步骤。 如有步骤同时使用脚本和容器操作,则容器操作将运行为同一网络上使用相同卷挂载的同级容器。
若不设置 container
,所有步骤将直接在 runs-on
指定的主机上运行,除非步骤引用已配置为在容器中运行的操作。
示例:在容器中运行作业
name: CI
on:
push:
branches: [ main ]
jobs:
container-test-job:
runs-on: ubuntu-latest
container:
image: node:14.16
env:
NODE_ENV: development
ports:
- 80
volumes:
- my_docker_volume:/volume_mount
options: --cpus 1
steps:
- name: Check for dockerenv file
run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)
只指定容器映像时,可以忽略 image
关键词。
jobs:
container-test-job:
runs-on: ubuntu-latest
container: node:14.16
jobs.<job_id>.container.image
使用 jobs.<job_id>.container.image
定义要用作运行操作的容器的 Docker 映像。 值可以是 Docker Hub 映像名称或注册表名称。
jobs.<job_id>.container.credentials
如果映像的容器注册表需要身份验证才能拉取映像,可以使用 jobs.<job_id>.container.credentials
设置 username
和 password
的 map
。 凭据与您提供给 Docker 登录
命令的值相同。
示例:定义容器注册表的凭据
container:
image: ghcr.io/owner/image
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
jobs.<job_id>.container.env
使用 jobs.<job_id>.container.env
在容器中设置环境变量的 map
。
jobs.<job_id>.container.ports
使用 jobs.<job_id>.container.ports
设置要在容器上公开的端口 array
。
jobs.<job_id>.container.volumes
使用 jobs.<job_id>.container.volumes
设置卷 array
供容器使用。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。
要指定卷,需指定来源和目标路径:
<source>:<destinationPath>
.
<source>
是主机上的卷名称或绝对路径,<destinationPath>
是容器中的绝对路径。
示例:在容器中装入卷
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.container.options
使用 jobs.<job_id>.container.options
配置其他 Docker 容器资源选项。 有关选项列表,请参阅“docker create
options”。
警告:不支持 --network
选项。
jobs.<job_id>.services
注:如果您的工作流程使用 Docker 容器操作、作业容器或服务容器,则必须使用 Linux 运行器:
- 如果您要使用 GitHub 托管的运行器,则必须使用 Ubuntu 运行器。
- 如果您要使用自托管运行器,则必须使用 Linux 机器作为运行器,并且必须安装 Docker。
用于为工作流程中的作业托管服务容器。 服务容器可用于创建数据库或缓存服务(如 Redis)。 运行器自动创建 Docker 网络并管理服务容器的生命周期。
如果将作业配置为在容器中运行,或者步骤使用容器操作,则无需映射端口来访问服务或操作。 Docker 会自动在同一个 Docker 用户定义的桥接网络上的容器之间显示所有端口。 您可以直接引用服务容器的主机名。 主机名自动映射到为工作流程中的服务配置的标签名称。
如果配置作业直接在运行器机器上运行,且您的步骤不使用容器操作,则必须将任何必需的 Docker 服务容器端口映射到 Docker 主机(运行器机器)。 您可以使用 localhost 和映射的端口访问服务容器。
有关网络服务容器之间差异的更多信息,请参阅“关于服务容器”。
示例:使用 localhost
此示例创建分别用于 nginx 和 redis 的两项服务。 指定 Docker 主机端口但不指定容器端口时,容器端口将随机分配给空闲端口。 GitHub 在 ${{job.services.<service_name>.ports}}
上下文中设置分配的容器端口。 在此示例中,可以使用 ${{ job.services.nginx.ports['8080'] }}
和 ${{ job.services.redis.ports['6379'] }}
上下文访问服务容器端口。
services:
nginx:
image: nginx
# Map port 8080 on the Docker host to port 80 on the nginx container
ports:
- 8080:80
redis:
image: redis
# Map TCP port 6379 on Docker host to a random free port on the Redis container
ports:
- 6379/tcp
jobs.<job_id>.services.<service_id>.image
要用作运行操作的服务容器的 Docker 镜像。 值可以是 Docker Hub 映像名称或注册表名称。
jobs.<job_id>.services.<service_id>.credentials
如果映像的容器注册表需要身份验证才能拉取映像,可以使用 jobs.<job_id>.container.credentials
设置 username
和 password
的 map
。 凭据与您提供给 Docker 登录
命令的值相同。
示例
services:
myservice1:
image: ghcr.io/owner/myservice1
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
myservice2:
image: dockerhub_org/myservice2
credentials:
username: ${{ secrets.DOCKER_USER }}
password: ${{ secrets.DOCKER_PASSWORD }}
jobs.<job_id>.services.<service_id>.env
在服务容器中设置环境变量的 map
。
jobs.<job_id>.services.<service_id>.ports
设置要在服务容器上显示的端口 array
。
jobs.<job_id>.services.<service_id>.volumes
设置要使用的服务容器卷的 array
。 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。
要指定卷,需指定来源和目标路径:
<source>:<destinationPath>
.
<source>
是主机上的卷名称或绝对路径,<destinationPath>
是容器中的绝对路径。
示例
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.services.<service_id>.options
附加 Docker 容器资源选项。 有关选项列表,请参阅“docker create
options”。
警告:不支持 --network
选项。
过滤器模式备忘清单
您可以在路径、分支和标记过滤器中使用特殊字符。
*
: 匹配零个或多个字符,但不匹配/
字符。 例如,Octo*
匹配Octocat
。**
: 匹配零个或多个任何字符。?
:匹配零个或一个前缀字符。+
: 匹配一个或多个前置字符。[]
匹配列在括号中或包含在范围内的一个字符。 范围只能包含a-z
、A-Z
和0-9
。 例如,范围[0-9a-z]
匹配任何数字或小写字母。 例如,[CB]at
匹配Cat
或Bat
,[1-2]00
匹配100
和200
。!
:在模式开始时,它将否定以前的正模式。 如果不是第一个字符,它就没有特殊的意义。
字符 *
、[
和 !
是 YAML 中的特殊字符。 如果模式以 *
、[
或 !
开头,必须用引号括住模式。
# Valid
- '**/README.md'
# Invalid - creates a parse error that
# prevents your workflow from running.
- **/README.md
有关分支、标记和路径筛选器语法的更多信息,请参阅“on.<push>.<branches|tags>
”、“on.<pull_request>.<branches|tags>
”和“on.<push|pull_request>.paths
”。
匹配分支和标记的模式
模式 | 描述 | 示例匹配 |
---|---|---|
feature/* | * 通配符匹配任何字符,但不匹配斜杠 (/ )。 | feature/my-branch feature/your-branch |
feature/** | ** 通配符匹配任何字符,包括分支和标记名称中的斜杠 (/ )。 | feature/beta-a/my-branch feature/your-branch feature/mona/the/octocat |
main releases/mona-the-octocat | 匹配分支或标记名称的确切名称。 | main releases/mona-the-octocat |
'*' | 匹配所有不包含斜杠 (/ ) 的分支和标记名称。 * 字符是 YAML 中的特殊字符。 当模式以 * 开头时,您必须使用引号。 | main releases |
'**' | 匹配所有分支和标记名称。 这是不使用 branches or tags 过滤器时的默认行为。 | all/the/branches every/tag |
'*feature' | * 字符是 YAML 中的特殊字符。 当模式以 * 开头时,您必须使用引号。 | mona-feature feature ver-10-feature |
v2* | 匹配以 v2 开头的分支和标记名称。 | v2 v2.0 v2.9 |
v[12].[0-9]+.[0-9]+ | 将所有语义版本控制分支和标记与主要版本 1 或 2 匹配. | v1.10.1 v2.0.0 |
匹配文件路径的模式
路径模式必须匹配整个路径,并从仓库根开始。
模式 | 匹配描述 | 示例匹配 |
---|---|---|
'*' | * 通配符匹配任何字符,但不匹配斜杠 (/ )。 * 字符是 YAML 中的特殊字符。 当模式以 * 开头时,您必须使用引号。 | README.md server.rb |
'*.jsx?' | ? 个字符匹配零个或一个前缀字符。 | page.js page.jsx |
'**' | The ** 通配符匹配任何字符,包括斜杠 (/ )。 这是不使用 path 过滤器时的默认行为。 | all/the/files.md |
'*.js' | * 通配符匹配任何字符,但不匹配斜杠 (/ )。 匹配仓库根目录上的所有 .js 文件。 | app.js index.js |
'**.js' | 匹配仓库中的所有 .js 文件。 | index.js js/index.js src/js/app.js |
docs/* | 仓库根目录下 docs 根目录中的所有文件。 | docs/README.md docs/file.txt |
docs/** | 仓库根目录下 /docs 目录中的任何文件。 | docs/README.md docs/mona/octocat.txt |
docs/**/*.md | docs 目录中任意位置具有 .md 后缀的文件。 | docs/README.md docs/mona/hello-world.md docs/a/markdown/file.md |
'**/docs/**' | 仓库中任意位置 docs 目录下的任何文件。 | docs/hello.md dir/docs/my-file.txt space/docs/plan/space.doc |
'**/README.md' | 仓库中任意位置的 README.md 文件。 | README.md js/README.md |
'**/*src/**' | 仓库中任意位置具有 src 后缀的文件夹中的任何文件。 | a/src/app.js my-src/code/js/app.js |
'**/*-post.md' | 仓库中任意位置具有后缀 -post.md 的文件。 | my-post.md path/their-post.md |
'**/migrate-*.sql' | 仓库中任意位置具有前缀 migrate- 和后缀 .sql 的文件。 | migrate-10909.sql db/migrate-v1.0.sql db/sept/migrate-v1.sql |
*.md !README.md | 模式前使用感叹号 (! ) 对其进行否定。 当文件与模式匹配并且也匹配文件后面定义的否定模式时,则不包括该文件。 | hello.md Does not match README.md docs/hello.md |
*.md !README.md README* | 按顺序检查模式。 否定前一个模式的模式将重新包含文件路径。 | hello.md README.md README.doc |