注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。
关于表达式
您可以使用表达式程序化设置工作流程文件中的环境变量和访问上下文。 表达式可以是文字值、上下文引用或函数的任意组合。 您可以使用运算符组合文字、上下文引用和函数。 有关上下文的详细信息,请参阅“上下文”。
表达式通常与工作流文件中的条件 if
关键字一起使用,以确定是否应运行步骤。 如果 if
条件为 true
,该步骤将运行。
您需要使用特定语法指示 GitHub 对表达式求值,而不是将其视为字符串。
${{ <expression> }}
注意:此规则的例外是当你在 if
子句中使用表达式时,通常可以有选择地忽略 ${{
和 }}
。 有关 if
条件的详细信息,请参阅“GitHub Actions 的工作流语法”。
警告:创建工作流程和操作时,应始终考虑代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 有关详细信息,请参阅“GitHub Actions 的安全强化”。
设置环境变量的示例
env:
MY_ENV_VAR: ${{ <expression> }}
文本
作为表达式的一部分,可使用 boolean
、null
、number
或 string
数据类型。
数据类型 | 文本值 |
---|---|
boolean | true 或 false |
null | null |
number | JSON 支持的任何数字格式。 |
string | 无需将字符串括在 ${{ 和 }} 中。 但是,如果这样做,则必须在字符串两边使用单引号 (' )。 若要使用文本单引号,请使用额外的单引号 ('' ) 转义文本单引号。 用双引号 (" ) 括起来会引发错误。 |
请注意,在条件中,假值(false
、0
、-0
、""
、''
、null
)被强制转换为 false
,且真值(true
和其他非假值)被强制转换为 true
。
文本示例
env:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99e-2 }}
myString: Mona the Octocat
myStringInBraces: ${{ 'It''s open source!' }}
运算符
运算符 | 说明 |
---|---|
( ) | 逻辑分组 |
[ ] | 索引 |
. | 属性取消引用 |
! | Not |
< | 小于 |
<= | 小于或等于 |
> | 大于 |
>= | 大于或等于 |
== | 等于 |
!= | 不等于 |
&& | 且 |
|| | 或 |
注意:
GitHub 进行宽松的等式比较。
-
如果类型不匹配,GitHub 强制转换类型为数字。 GitHub 使用这些转换将数据类型转换为数字:
类型 结果 Null 0
布尔 true
返回1
false
返回0
String 从任何合法的 JSON 数字格式进行分析,否则为 NaN
。
注意:空字符串返回0
。数组 NaN
Object NaN
-
当
NaN
是任何关系比较(>
、<
、>=
、<=
)的操作数之一,结果始终为false
。 有关详细信息,请参阅“NaN Mozilla 文档”。 -
GitHub 在比较字符串时忽略大小写。
-
对象和数组仅在为同一实例时才视为相等。
GitHub 提供可在表达式中使用的类似三元运算符的行为。 通过以这种方式使用三元运算符,可以根据条件动态设置环境变量的值,而无需为每个可能的选项编写单独的 if-else 块。
示例
env:
MY_ENV_VAR: ${{ github.ref == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }}
在此示例中,我们使用三元运算符根据 GitHub 引用是否设置为 refs/heads/main
来设置 MY_ENV_VAR
环境变量的值。 如果是,则变量设置为 value_for_main_branch
。 否则,设置为 value_for_other_branches
。
请务必注意,&&
后的第一个值必须是真值。 否则,||
后的值总会被返回。
函数
GitHub 提供一组内置的函数,可用于表达式。 有些函数抛出值到字符串以进行比较。 GitHub 使用这些转换将数据类型转换为字符串:
类型 | 结果 |
---|---|
Null | '' |
布尔 | 'true' 或 'false' |
数字 | 十进制格式,对大数字使用指数 |
数组 | 数组不转换为字符串 |
对象 | 对象不转换为字符串 |
contains
contains( search, item )
如果 search
包含 item
,则返回 true
。 如果 search
是一个数组,item
是数组中的一个元素,此函数将返回 true
。 如果 search
是一个字符串,item
是 search
的 substring,此函数将返回 true
。 此函数不区分大小写。 抛出值到字符串。
使用字符串的示例
contains('Hello world', 'llo')
返回 true
。
使用对象筛选器的示例
如果与事件相关的问题具有标签“bug”,contains(github.event.issue.labels.*.name, 'bug')
便会返回 true
。
有关详细信息,请参阅“对象筛选器”。
匹配字符串数组的示例
可以将 contains()
与 fromJSON()
配合使用来检查字符串数组是否包含 item
,而不是编写 github.event_name == "push" || github.event_name == "pull_request"
。
例如,如果 github.event_name
是“push”或“pull_request”,contains(fromJSON('["push", "pull_request"]'), github.event_name)
便会返回 true
。
startsWith
startsWith( searchString, searchValue )
如果 searchString
以 searchValue
开头,将返回 true
。 此函数不区分大小写。 抛出值到字符串。
startsWith
的示例
startsWith('Hello world', 'He')
返回 true
。
endsWith
endsWith( searchString, searchValue )
如果 true
以 searchString
结尾,则返回 searchValue
。 此函数不区分大小写。 抛出值到字符串。
endsWith
的示例
endsWith('Hello world', 'ld')
返回 true
。
format
format( string, replaceValue0, replaceValue1, ..., replaceValueN)
将 string
中的值替换为变量 replaceValueN
。 string
中的变量是使用 {N}
语法指定的,其中 N
是一个整数。 必须至少指定一个 replaceValue
和 string
。 可使用的变量 (replaceValueN
) 的数量没有上限。 使用双小括号逸出大括号。
format
的示例
format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')
返回“Hello Mona the Octocat”。
逸出括号示例
format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat')
返回“{Hello Mona the Octocat!}”。
join
join( array, optionalSeparator )
array
的值可以是数组,也可以是字符串。 array
中的所有值都连接成一个字符串。 如果提供 optionalSeparator
,则它将插入到连接的值之间, 否则使用默认分隔符 ,
。 抛出值到字符串。
join
的示例
join(github.event.issue.labels.*.name, ', ')
可能会返回“出现 bug,需要帮助”
toJSON
toJSON(value)
对 value
返回适合打印的 JSON 表示形式。 您可以使用此函数调试上下文中提供的信息。
toJSON
的示例
toJSON(job)
可能会返回 { "status": "success" }
fromJSON
fromJSON(value)
返回 value
的 JSON 对象或 JSON 数据类型。 可以使用此函数将 JSON 对象作为计算表达式提供,或使用此函数转换可以 JSON 或 JavaScript 表示的任何数据类型,例如字符串、布尔值、null 值、数组和对象。
返回 JSON 对象的示例
此工作流在一个作业中设置 JSON 矩阵,并使用输出和 fromJSON
将其传递给下一个作业。
name: build on: push jobs: job1: runs-on: ubuntu-latest outputs: matrix: ${{ steps.set-matrix.outputs.matrix }} steps: - id: set-matrix run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT job2: needs: job1 runs-on: ubuntu-latest strategy: matrix: ${{ fromJSON(needs.job1.outputs.matrix) }} steps: - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"
name: build
on: push
jobs:
job1:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- id: set-matrix
run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
job2:
needs: job1
runs-on: ubuntu-latest
strategy:
matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
steps:
- run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"
返回 JSON 数据类型的示例
此工作流使用 fromJSON
将环境变量从字符串转换为布尔值或整数。
name: print on: push env: continue: true time: 3 jobs: job1: runs-on: ubuntu-latest steps: - continue-on-error: ${{ fromJSON(env.continue) }} timeout-minutes: ${{ fromJSON(env.time) }} run: echo ...
name: print
on: push
env:
continue: true
time: 3
jobs:
job1:
runs-on: ubuntu-latest
steps:
- continue-on-error: ${{ fromJSON(env.continue) }}
timeout-minutes: ${{ fromJSON(env.time) }}
run: echo ...
工作流使用 fromJSON()
函数将环境变量 continue
从字符串转换为布尔值,从而允许其决定是否在出错时继续。 同样,它将 time
环境变量从字符串转换为整数,以分钟为单位设置作业的超时值。
hashFiles
hashFiles(path)
返回与 path
模式匹配的文件集的单个哈希。 可以提供用逗号分隔的单个 path
模式或多个 path
模式。 path
与 GITHUB_WORKSPACE
目录相关,且仅包含 GITHUB_WORKSPACE
内的文件。 此函数为每个匹配的文件计算单独的 SHA-256 哈希, 然后使用这些哈希来计算文件集的最终 SHA-256 哈希。 如果 path
模式与任何文件都不匹配,则返回空字符串。 有关 SHA-256 的详细信息,请参阅“SHA-2”。
您可以使用模式匹配字符来匹配文件名。 与 hashFiles
匹配的模式遵循 glob 模式匹配,并且在 Windows 上不区分大小写。 有关支持的模式匹配字符的详细信息,请参阅 @actions/glob
文档中的模式部分。
单一模式示例
匹配存储库中的任何 package-lock.json
文件。
hashFiles('**/package-lock.json')
多个模式示例
为存储库中的任何 package-lock.json
和 Gemfile.lock
文件创建哈希。
hashFiles('**/package-lock.json', '**/Gemfile.lock')
状态检查函数
可以将以下状态检查函数用作 if
条件中的表达式。 除非包含这些函数之一,否则将应用 success()
的默认状态检查。 有关 if
条件的详细信息,请参阅“GitHub Actions 的工作流语法”和“GitHub Actions 的元数据语法”。
success
当前面的所有步骤都成功时返回 true
。
success
的示例
steps:
...
- name: The job has succeeded
if: ${{ success() }}
通用
导致步骤始终执行,并返回 true
,即使取消也一样。 always
表达式最适用于步骤级别或预期即使作业取消仍会运行的任务。 例如,即使作业取消,仍然可以使用 always
发送日志。
警告: 避免对任何可能出现严重故障的任务(例如获取源)使用 always
,否则工作流可能会挂起,直到超时。如果要运行作业或步骤且不考虑其成功或失败,请使用推荐的替代方法:if: ${{ !cancelled() }}
always
的示例
if: ${{ always() }}
cancelled
如果工作流被取消,则返回 true
。
cancelled
的示例
if: ${{ cancelled() }}
失败
如果作业的任何先前步骤失败,将返回 true
。 如果有一系列依赖项作业,则 failure()
在任何上级作业失败时返回 true
。
failure
的示例
steps:
...
- name: The job has failed
if: ${{ failure() }}
有条件的失败
可以包含一个在失败后运行的步骤的额外条件,但仍必须包含 failure()
以覆盖自动应用于不包含状态检查函数的 if
条件的默认 success()
状态检查。
有条件 failure
的示例
steps:
...
- name: Failing step
id: demo
run: exit 1
- name: The demo step has failed
if: ${{ failure() && steps.demo.conclusion == 'failure' }}
对象过滤器
可使用 *
语法来应用筛选器并选择集合中的匹配项。
例如,考虑名为 fruits
的对象数组。
[
{ "name": "apple", "quantity": 1 },
{ "name": "orange", "quantity": 2 },
{ "name": "pear", "quantity": 1 }
]
筛选器 fruits.*.name
返回数组 [ "apple", "orange", "pear" ]
。
还可以对某个对象使用 *
语法。 例如,假设有一个名为 vegetables
的对象。
{
"scallions":
{
"colors": ["green", "white", "red"],
"ediblePortions": ["roots", "stalks"],
},
"beets":
{
"colors": ["purple", "red", "gold", "white", "pink"],
"ediblePortions": ["roots", "stems", "leaves"],
},
"artichokes":
{
"colors": ["green", "purple", "red", "black"],
"ediblePortions": ["hearts", "stems", "leaves"],
},
}
筛选器 vegetables.*.ediblePortions
的计算结果如下:
[
["roots", "stalks"],
["hearts", "stems", "leaves"],
["roots", "stems", "leaves"],
]
由于对象不保留顺序,因此无法保证输出的顺序。