注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
关于工作流程的 YAML 语法
工作流程文件使用 YAML 语法,必须有 .yml
或 .yaml
文件扩展名。 如果您是 YAML 的新用户并想要了解更多信息,请参阅“Y 分钟了解 YAML”。
必须将工作流程文件存储在仓库的 .github/workflows
目录中。
name
工作流程的名称。 GitHub 在仓库的操作页面上显示工作流程的名称。 如果省略 name
,GitHub 将其设置为相对于仓库� �目录的工作流程文件路径。
on
To automatically trigger a workflow, use on
to define which events can cause the workflow to run. 有关可用事件的列表,请参阅“触发工作流程的事件”。
You can define single or multiple events that can a trigger workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. 以下各节介绍了这些选项。
使用单个事件
例如,推送到工作流程存储库中的任何分支时,将运行具有以下 on
值的工作流程:
on: push
使用多个事件
您可以指定单个事件或多个事件。 例如,当向存储库中的任何分支进行推送或有人复刻存储库时,将运行具有以下 on
值的工作流程:
on: [push, fork]
如果指定多个事件,则只需发生其中一个事件即可触发工作流程。 如果工作流程的多个触发事件同时发生,则将触发多个工作流程运行。
Using activity types
Some events have activity types that give you more control over when your workflow should run. Use on.<event_name>.types
to define the type of event activity that will trigger a workflow run.
For example, the issue_comment
event has the created
, edited
, and deleted
activity types. If your workflow triggers on the label
event, it will run whenever a label is created, edited, or deleted. If you specify the created
activity type for the label
event, your workflow will run when a label is created but not when a label is edited or deleted.
on:
label:
types:
- created
If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.
on:
issue:
types:
- opened
- labeled
有关每个事件及其活动类型的更多信息,请参阅“触发工作流程的事件”。
使用筛选器
Some events have filters that give you more control over when your workflow should run.
For example, the push
event has a branches
filter that causes your workflow to run only when a push to a branch that matches the branches
filter occurs, instead of when any push occurs.
on:
push:
branches:
- main
- 'releases/**'
将活动类型和筛选器用于多个事件
如果为事件指定活动类型或筛选器,并且工作流程触发多个事件,则必须单独配置每个事件。 您必须为所有事件附� 冒号 (:
),包括没有配置的事件。
例如,使用以下 on
值的工作流程将在以下情况下运行:
- 创建� �签
- 推送到存储库中的
main
分支 - 推送到启用了 GitHub Pages 的分支
on:
label:
types:
- created
push:
branches:
- main
page_build:
on.<event_name>.types
Use on.<event_name>.types
to define the type of activity that will trigger a workflow run. 大多数 GitHub 事件由多种活动触发。 For example, the label
is triggered when a label is created
, edited
, or deleted
. 通过 types
关键词可缩小触发工作流程运行的活动类型的范围。 如果只有一种活动类型可触发 web 挂钩事件,就没有必要使用 types
关键词。
您可以使用事件 types
的数组。 有关每个事件及其活动类型的更多信息,请参阅“触发工作流程的事件”。
on:
label:
types: [created, edited]
on.<pull_request|pull_request_target>.<branches|branches-ignore>
When using the pull_request
and pull_request_target
events, you can configure a workflow to run only for pull requests that target specific branches.
Use the branches
filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore
filter when you only want to exclude branch name patterns. You cannot use both the branches
and branches-ignore
filters for the same event in a workflow.
If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The branches
and branches-ignore
keywords accept glob patterns that use characters like *
, **
, +
, ?
, !
and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \
. 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。
Example: Including branches
The patterns defined in branches
are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request
event for a pull request targeting:
- A branch named
main
(refs/heads/main
) - A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name starts with
releases/
, likereleases/10
(refs/heads/releases/10
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
Example: Excluding branches
When a pattern matches the branches-ignore
pattern, the workflow will not run. The patterns defined in branches
are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request
event unless the pull request is targeting:
- A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name matches
releases/**-alpha
, likereleases/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'
Example: Including and excluding branches
You cannot use branches
and branches-ignore
to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the branches
filter along with the !
character to indicate which branches should be excluded.
If you define a branch with the !
character, you must also define at least one branch without the !
character. If you only want to exclude branches, use branches-ignore
instead.
您定义模式事项的顺序。
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除 Git 引用。 - 否定匹配后的匹配肯定模式将再次包含 Git 引用。
The following workflow will run on pull_request
events for pull requests that target releases/10
or releases/beta/mona
, but not for pull requests that target releases/10-alpha
or releases/beta/3-alpha
because the negative pattern !releases/**-alpha
follows the positive pattern.
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.push.<branches|tags|branches-ignore|tags-ignore>
When using the push
event, you can configure a workflow to run on specific branches or tags.
Use the branches
filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore
filter when you only want to exclude branch name patterns. You cannot use both the branches
and branches-ignore
filters for the same event in a workflow.
Use the tags
filter when you want to include tag name patterns or when you want to both include and exclude tag names patterns. Use the tags-ignore
filter when you only want to exclude tag name patterns. You cannot use both the tags
and tags-ignore
filters for the same event in a workflow.
If you define only tags
/tags-ignore
or only branches
/branches-ignore
, the workflow won't run for events affecting the undefined Git ref. If you define neither tags
/tags-ignore
or branches
/branches-ignore
, the workflow will run for events affecting either branches or tags. If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
branches
、branches-ignore
、tags
和 tags-ignore
关键词接受使用 *
、**
、+
、?
、!
等字符匹配多个分支或� �记名称的 glob 模式。 如果名称包含其中任一字符,而您想要逐字匹配,则需要使用 \
转义每个特殊字符。 有关 glob 模式的更多信息,请参阅“过滤器模式备忘清单”。
示例:包括分支和� �记
在 branches
和 tags
中定义的模式� �据 Git ref 的名称进行评估。 For example, the following workflow would run whenever there is a push
event to:
- A branch named
main
(refs/heads/main
) - A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name starts with
releases/
, likereleases/10
(refs/heads/releases/10
) - A tag named
v2
(refs/tags/v2
) - A tag whose name starts with
v1.
, likev1.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.*
Example: Excluding branches and tags
When a pattern matches the branches-ignore
or tags-ignore
pattern, the workflow will not run. 在 branches
和 tags
中定义的模式� �据 Git ref 的名称进行评估。 For example, the following workflow would run whenever there is a push
event, unless the push
event is to:
- A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name matches
releases/**-alpha
, likebeta/3-alpha
(refs/releases/beta/3-alpha
) - A tag named
v2
(refs/tags/v2
) - A tag whose name starts with
v1.
, likev1.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.*
Example: Including and excluding branches and tags
You can't use branches
and branches-ignore
to filter the same event in a single workflow. Similarly, you can't use tags
and tags-ignore
to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use the branches
or tags
filter along with the !
character to indicate which branches or tags should be excluded.
If you define a branch with the !
character, you must also define at least one branch without the !
character. If you only want to exclude branches, use branches-ignore
instead. Similarly, if you define a tag with the !
character, you must also define at least one tag without the !
character. If you only want to exclude tags, use tags-ignore
instead.
您定义模式事项的顺序。
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除 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>
When using the push
and pull_request
events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.
Use the paths
filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use the paths-ignore
filter when you only want to exclude file path patterns. You cannot use both the paths
and paths-ignore
filters for the same event in a workflow.
If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The paths
and paths-ignore
keywords accept glob patterns that use the *
and **
wildcard characters to match more than one path name. 更多信息请参阅“过滤器模式备忘清单”。
示例:包括路径
如果至少有一个路径与 paths
过滤器中的模式匹配,工作流程将会运行。 For example, the following workflow would run anytime you push a JavaScript file (.js
).
on:
push:
paths:
- '**.js'
注意:如果由于路径过滤、 分支过滤或提交消息而跳过工作流程,则与该工作流程关联的检查将保持“挂起”状态。 需要这些检查成功的拉取请求将被阻止合并。 For more information, see "Handling skipped but required checks."
Example: Excluding paths
当所有路径名称匹配 paths-ignore
中的模式时,工作流程不会运行。 If any path names do not match patterns in paths-ignore
, even if some path names match the patterns, the workflow will run.
具有以下路径过滤器的工作流程仅在 push
事件上运行,这些事件包括至少一个位于仓库� �目录的 docs
目录外的文件。
on:
push:
paths-ignore:
- 'docs/**'
Example: Including and excluding paths
You can not use paths
and paths-ignore
to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use the paths
filter along with the !
character to indicate which paths should be excluded.
If you define a path with the !
character, you must also define at least one path without the !
character. If you only want to exclude paths, use paths-ignore
instead.
您定义模式事项的顺序:
- 肯定匹配后的匹配否定模式(前缀为
!
)将排除路径。 - 否定匹配后的匹配肯定模式将再次包含路径。
只要 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
You can use on.schedule
to define a time schedule for your workflows. 您可以使用 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/**'
A workflow with the following trigger will only run when the workflow named Build
runs on a branch that is not named canary
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
You cannot use both the branches
and branches-ignore
filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use the branches
filter along with the !
character to indicate which branches should be excluded.
您定义模式事项的顺序。
- A matching negative pattern (prefixed with
!
) after a positive match will exclude the branch. - A matching positive pattern after a negative match will include the branch again.
For example, a workflow with the following trigger will run when the workflow named Build
runs on a branch that is named releases/10
or releases/beta/mona
but will not releases/10-alpha
, releases/beta/3-alpha
, or main
.
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
on.workflow_dispatch.inputs
When using the workflow_dispatch
event, you can optionally specify inputs that are passed to the workflow.
The triggered workflow receives the inputs in the github.event.inputs
context. For more information, see "Contexts."
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 }}
env
环境变量的 map
可用于工作流程中所有作业的步骤。 您还可以设置仅适用于单个作业的步骤或单个步骤的环境变量。 更多信息请参阅 jobs.<job_id>.env
and jobs.<job_id>.steps[*].env
。
env
� 射中的变量不能� �据� 射中的其他变量进行定义。
当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的环境变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。
示例
env:
SERVER: production
defaults
Use defaults
to create a map
of default settings that will apply to all jobs in the workflow. 您也可以设置只可用于作业的默认设置。 更多信息请参阅 jobs.<job_id>.defaults
。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
defaults.run
You can use defaults.run
to provide default shell
and working-directory
options for all run
steps in a workflow. 您也可以设置只可用于作业的 run
默认设置。 更多信息请参阅 jobs.<job_id>.defaults.run
。 您不能在此关键词中使用上下文或表达式。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
Example: Set the default shell and working directory
defaults:
run:
shell: bash
working-directory: scripts
jobs
A workflow run is made up of one or more jobs
, which run in parallel by default. 要按顺序运行作业,您可以使用 <job_id>needs
关键词在其他作业上定义依赖项。
每个作业在 runs-on
指定的运行器环境中运行。
在工作流程的使用限制之内可运行� 限数量的作业。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
If you need to find the unique identifier of a job running in a workflow run, you can use the GitHub Enterprise Server API. 更多信息请参阅“工作流程作业”。
jobs.<job_id>
Use jobs.<job_id>
to give your job a unique identifier. 键值 job_id
是一个字符串,其值是作业配置数据的� 像。 必须将 <job_id>
替换为 jobs
对象唯一的字符串。 <job_id>
必须以字母或 _
开头,并且只能包含字母数字字符、-
或 _
。
Example: Creating jobs
In this example, two jobs have been created, and their job_id
values are my_first_job
and my_second_job
.
jobs:
my_first_job:
name: My first job
my_second_job:
name: My second job
jobs.<job_id>.name
Use jobs.<job_id>.name
to set a name for the job, which is displayed in the GitHub UI.
jobs.<job_id>.needs
Use jobs.<job_id>.needs
to identify any jobs that must complete successfully before this job will run. 它可以是一个字符串,也可以是字符串数组。 如果某个作业失败,则所有需要它的作业都会被跳过,除非这些作业使用让该作业继续的条件表达式。 If a run contains a series of jobs that need each other, a failure applies to all jobs in the dependency chain from the point of failure onwards.
Example: Requiring successful dependent jobs
jobs:
job1:
job2:
needs: job1
job3:
needs: [job1, job2]
在此示例中,job1
必须在 job2
开始之前成功完成,而 job3
要等待 job1
和 job2
完成。
此示例中的作业按顺序运行:
job1
job2
job3
Example: Not requiring successful dependent jobs
jobs:
job1:
job2:
needs: job1
job3:
if: ${{ always() }}
needs: [job1, job2]
在此示例中,job3
使用 always()
条件表达式,� 此它始终在 job1
和 job2
完成后运行,不管它们是否成功。 更多信息请参阅“表达式”。
jobs.<job_id>.if
You can use the jobs.<job_id>.if
conditional to prevent a job from running unless a condition is met. 您可以使用任何支持上下文和表达式来创建条件。
在 if
条件下使用表达式时,可以省略表达式语法 (${{ }}
),� 为 GitHub 会自动将 if
条件作为表达式求值。 更多信息请参阅“表达式”。
Example: Only run job for specific repository
This example uses if
to control when the production-deploy
job can run. It will only run if the repository is named octo-repo-prod
and is within the octo-org
organization. Otherwise, the job will be marked as skipped.
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
Use jobs.<job_id>.runs-on
to define the type of machine to run the job on. You can provide runs-on
as a single string or as an array of strings. If you specify an array of strings, your workflow will run on a self-hosted runner whose labels match all of the specified runs-on
values, if available. If you would like to run your workflow on multiple machines, use jobs.<job_id>.strategy
.
注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
Choosing GitHub-hosted runners
如果使用 GitHub 托管的运行器,每个作业将在 runs-on
指定的虚拟环境的新实例中运行。
可用的 GitHub 托管的运行器类型包括:
虚拟环境 | YAML 工作流程� �签 | 注: |
---|---|---|
Windows Server 2022 | windows-latest 或 windows-2022 |
The windows-latest label currently uses the Windows Server 2022 runner image.
|
Windows Server 2019 | windows-2019 |
|
Ubuntu 22.04 | ubuntu-22.04 |
Ubuntu 22.04 is currently in public beta. |
Ubuntu 20.04 | ubuntu-latest 或 ubuntu-20.04 |
|
Ubuntu 18.04 | ubuntu-18.04 |
|
macOS Monterey 12 | macos-12 |
|
macOS Big Sur 11 | macos-latest 或 macos-11 |
The macos-latest label currently uses the macOS 11 runner image.
|
macOS Catalina 10.15 | macos-10.15 |
Note: The -latest
virtual environments 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.
Note: Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.
Example: Specifying an operating system
runs-on: ubuntu-latest
更多信息请参阅“GitHub 托管的运行器的虚拟环境”。
Choosing self-hosted runners
要为工作指定自托管的运行器,请在工作流程文件中使用自托管运行器� �签配置 runs-on
。
所有自托管运行器都有 self-hosted
� �签。 仅使用此� �签将选择任何自托管运行器。 To select runners that meet certain criteria, such as operating system or architecture, we recommend providing an array of labels that begins with self-hosted
(this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.
Although the self-hosted
label is not required, we strongly recommend specifying it when using self-hosted runners to ensure that your job does not unintentionally specify any current or future GitHub-hosted runners.
Example: Using labels for runner selection
runs-on: [self-hosted, linux]
更多信息请参阅“关于自托管的运行器”和“在工作流程中使用自托管的运行器”。
jobs.<job_id>.environment
Use jobs.<job_id>.environment
to define the environment that the job references. 在将引用环境的作业发送到运行器之前,必须通过所有环境保护规则。 更多信息请参阅“使用环境进行部署”。
您可以将环境仅作为环境 name
,或作为具有 name
和 url
的环境变量。 URL � 射到部署 API 中的 environment_url
。 有关部署 API 的更多信息,请参阅“部署”。
Example: Using a single environment name
environment: staging_environment
Example: Using environment name and URL
environment:
name: production_environment
url: https://github.com
The URL can be an expression and can use any context except for the secrets
context. For more information about expressions, see "Expressions."
Example: Using output as URL
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.outputs
You can use jobs.<job_id>.outputs
to create a map
of outputs for a job. 作业输出可用于所有依赖此作业的下游作业。 有关定义作业依赖项的更多信息,请参阅 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.
Job outputs containing expressions are evaluated on the runner at the end of each job. 包含密� �的输出在运行器上编辑,不会发送至 GitHub Actions。
要在依赖的作业中使用作业输出, 您可以使用 needs
上下文。 更多信息请参阅“上下文”。
Example: Defining outputs for a job
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
Use jobs.<job_id>.defaults
to create a map
of default settings that will apply to all steps in the job. 您也可以设置整个工作流程的默认设置。 For more information, see defaults
.
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
jobs.<job_id>.defaults.run
Use jobs.<job_id>.defaults.run
to provide default shell
and working-directory
to all run
steps in the job. 此部分不允许上下文和表达式。
您可以为作业中的所有 run
步骤提供默认的 shell
和 working-directory
选项。 您也可以为整个工作流程设置 run
的默认设置。 更多信息请参阅 jobs.defaults.run
。 您不能在此关键词中使用上下文或表达式。
使用相同名称定义了多个默认设置时,GitHub 会使用最具体的默认设置。 例如,在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。
Example: Setting default run
step options for a job
jobs:
job1:
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: scripts
jobs.<job_id>.steps
作业包含一系列任务,称为 steps
。 步骤可以运行命令、运行设置任务,或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。 并非所有步骤都会运行操作,但所有操作都会作为步骤运行。 每个步骤在运行器环境中以其自己的进程运行,且可以访问工作区和文件系统。 � 为步骤以自己的进程运行,所以步骤之间不会保留环境变量的更改。 GitHub 提供内置的步骤来设置和完成作业。
在工作流程的使用限制之内可运行� 限数量的步骤。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
示例
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 参数 | 描述 | 内部运行命令 |
---|---|---|---|
所有 | 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
的快速失败行为:bash
和内置shell
的默认值。 它还是未在非 Windows 平台上提供选项时的默认值。 - 您可以向 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 托管的运行器)和 “关于自托管的运行器”(对于自托管运行器使用限制)。
注意: The GITHUB_TOKEN
expires when a job finishes or after a maximum of 24 hours. 对于自托管运行器,如果作业超时大于 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 the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. 更多信息请参阅“对作业使用矩阵”。
jobs.<job_id>.strategy.matrix
Use jobs.<job_id>.strategy.matrix
to define a matrix of different job configurations. Within your matrix, define one or more variables followed by an array of values. For example, the following matrix has a variable called version
with the value [10, 12, 14]
and a variable called os
with the value [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
A job will run for each possible combination of the variables. In this example, the workflow will run six jobs, one for each combination of the os
and version
variables.
By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run. For example, the above matrix will create the jobs in the following order:
{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}
A matrix will generate a maximum of 256 jobs per workflow run. This limit applies to both GitHub Enterprise Server-hosted and self-hosted runners.
The variables that you define become properties in the matrix
context, and you can reference the property in other areas of your workflow file. In this example, you can use matrix.version
and matrix.os
to access the current value of version
and os
that the job is using. 更多信息请参阅“上下文”。
示例:使用单维矩阵
You can specify a single variable to create a single-dimension matrix.
For example, the following workflow defines the variable version
with the values [10, 12, 14]
. The workflow will run three jobs, one for each value in the variable. Each job will access the version
value through the matrix.version
context and pass the value as node-version
to the actions/setup-node
action.
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
示例:使用多维矩阵
You can specify multiple variables to create a multi-dimensional matrix. A job will run for each possible combination of the variables.
For example, the following workflow specifies two variables:
- Two operating systems specified in the
os
variable - Three Node.js versions specified in the
version
variable
The workflow will run six jobs, one for each combination of the os
and version
variables. Each job will set the runs-on
value to the current os
value and will pass the current version
value to the actions/setup-node
action.
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-18.04, ubuntu-20.04]
version: [10, 12, 14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.version }}
示例:使用上下文创建矩阵
You can use contexts to create matrices. 有关上下文的更多信息,请参阅“上下文”。
For example, the following workflow triggers on the repository_dispatch
event and uses information from the event payload to build the matrix. When a repository dispatch event is created with a payload like the one below, the matrix version
variable will have a value of [12, 14, 16]
. For more information about the repository_dispatch
trigger, see "Events that trigger workflows."
{
"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
Use jobs.<job_id>.strategy.matrix.include
to expand existing matrix configurations or to add new configurations. The value of include
is a list of objects.
For each object in the include
list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten.
For example, this matrix:
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
will result in six jobs with the following matrix combinations:
{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}
following this logic:
{color: green}
is added to all of the original matrix combinations because it can be added without overwriting any part of the original combinations.{color: pink, animal: cat}
addscolor:pink
only to the original matrix combinations that includeanimal: cat
. This overwrites thecolor: green
that was added by the previousinclude
entry.{fruit: apple, shape: circle}
addsshape: circle
only to the original matrix combinations that includefruit: apple
.{fruit: banana}
cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination.{fruit: banana, animal: cat}
cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. It does not add to the{fruit: banana}
matrix combination because that combination was not one of the original matrix combinations.
示例:展开配置
For example, the following workflow will run six jobs, one for each combination of os
and node
. When the job for the os
value of windows-latest
and node
value of 16
runs, an additional variable called npm
with the value of 6
will be included in the job.
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
示例:添� 配置
For example, this matrix will run 10 jobs, one for each combination of os
and version
in the matrix, plus a job for the os
value of windows-latest
and version
value of 17
.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
If you don't specify any matrix variables, all configurations under include
will run. For example, the following workflow would run two jobs, one for each include
entry. This lets you take advantage of the matrix strategy without having a fully populated matrix.
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
To remove specific configurations defined in the matrix, use jobs.<job_id>.strategy.matrix.exclude
. An excluded configuration only has to be a partial match for it to be excluded. For example, the following workflow will run nine jobs: one job for each of the 12 configurations, minus the one excluded job that matches {os: macos-latest, version: 12, environment: production}
, and the two excluded jobs that match {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
You can control how job failures are handled with jobs.<job_id>.strategy.fail-fast
and jobs.<job_id>.continue-on-error
.
jobs.<job_id>.strategy.fail-fast
applies to the entire matrix. If jobs.<job_id>.strategy.fail-fast
is set to true
, GitHub Enterprise Server will cancel all in-progress and queued jobs in the matrix if any job in the matrix fails. This property defaults to true
.
jobs.<job_id>.continue-on-error
applies to a single job. If jobs.<job_id>.continue-on-error
is true
, other jobs in the matrix will continue running even if the job with jobs.<job_id>.continue-on-error: true
fails.
You can use jobs.<job_id>.strategy.fail-fast
and jobs.<job_id>.continue-on-error
together. For example, the following workflow will start four jobs. For each job, continue-on-error
is determined by the value of matrix.experimental
. If any of the jobs with continue-on-error: false
fail, all jobs that are in progress or queued will be cancelled. If the job with continue-on-error: true
fails, the other jobs will not be affected.
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
By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. To set the maximum number of jobs that can run simultaneously when using a matrix
job strategy, use jobs.<job_id>.strategy.max-parallel
.
For example, the following workflow will run a maximum of two jobs at a time, even if there are runners available to run all six jobs at once.
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-18.04]
experimental: [false]
include:
- node: 15
os: ubuntu-18.04
experimental: true
jobs.<job_id>.container
Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:
- 如果您要使用 GitHub 托管的运行器,则必须使用 Ubuntu 运行器。
- 如果您要使用自托管运行器,则必须使用 Linux 机器作为运行器,并且必须安装 Docker。
Use jobs.<job_id>.container
to create a container to run any steps in a job that don't already specify a container. 如有步骤同时使用脚本和容器操作,则容器操作将运行为同一网络上使用相同卷挂载的同级容器。
若不设置 container
,所有步骤将直接在 runs-on
指定的主机上运行,除非步骤引用已配置为在容器中运行的操作。
Example: Running a job within a container
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
Use jobs.<job_id>.container.image
to define the Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.
jobs.<job_id>.container.credentials
如果� 像的容器注册表需要身份验证才能拉取� 像,可以使用 jobs.<job_id>.container.credentials
设置 username
和 password
的 map
。 凭据与您提供给 Docker 登录
命令的值相同。
Example: Defining credentials for a container registry
container:
image: ghcr.io/owner/image
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
jobs.<job_id>.container.env
Use jobs.<job_id>.container.env
to set a map
of environment variables in the container.
jobs.<job_id>.container.ports
Use jobs.<job_id>.container.ports
to set an array
of ports to expose on the container.
jobs.<job_id>.container.volumes
Use jobs.<job_id>.container.volumes
to set an array
of volumes for the container to use. 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。
要指定卷,需指定来源和目� �路径:
<source>:<destinationPath>
.
<source>
是主机上的卷名称或绝对路径,<destinationPath>
是容器中的绝对路径。
Example: Mounting volumes in a container
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.container.options
Use jobs.<job_id>.container.options
to configure additional Docker container resource options. 有关选项列表,请参阅“docker create
options”。
警告:不支持 --network
选项。
jobs.<job_id>.services
Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:
- 如果您要使用 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 |