注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
About expressions
You can use expressions to programmatically set environment variables in workflow files and access contexts. 表达式可以是文字值、上下文引用或函数的任意组合。 您可以使用运算符组合文字、上下文引用和函数。 For more information about contexts, see "Contexts."
表达式通常在工作流程文件中与条件性 if
关键词一起用来确定步骤是否应该运行。 当 if
条件为 true
时,步骤将会运行。
您需要使用特定语法指示 GitHub 对表达式求值,而不是将其视为字符串。
${{ <expression> }}
在 if
条件下使用表达式时,可以省略表达式语法 (${{ }}
),� 为 GitHub 会自动将 if
条件作为表达式求值。有关 if
条件的更多信息,请参阅“GitHub Actions 的工作流程语法”。
警告:创建工作流程和操作时,您应始终考虑您的代� �是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,� 为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。
if
条件的示例表达式
steps:
- uses: actions/hello-world-javascript-action@v1.1
if: ${{ <expression> }}
设置环境变量的示例
env:
MY_ENV_VAR: ${{ <expression> }}
文字
作为表达式的一部分,您可以使用 boolean
、null
、number
或 string
数据类型。
数据类型 | 文字值 |
---|---|
布尔值 | true 或 false |
null | null |
number | JSON 支持的任何数字� �式。 |
字符串 | You don't need to enclose strings in ${{ and }} . However, if you do, you must use single quotes (' ) around the string. To use a literal single quote, escape the literal single quote using an additional single quote ('' ). Wrapping with double quotes (" ) will throw an error. |
示例
env:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99-e2 }}
myString: Mona the Octocat
myStringInBraces: ${{ 'It''s open source!' }}
运算符
运算符 | 描述 |
---|---|
( ) | 逻辑分组 |
[ ] | 索引 |
. | Property de-reference |
! | 非 |
< | 小于 |
<= | 小于或等于 |
> | 大于 |
>= | 大于或等于 |
== | 等于 |
!= | 不等于 |
&& | 和 |
|| | 或 |
GitHub 进行宽松的等式比较。
-
如果类型不匹配,GitHub 强制转换类型为数字。 GitHub 使用这些转换将数据类型转换为数字:
类型 结果 Null 0
布尔值 true
返回1
false
返回0
字符串 从任何合法 JSON 数字� �式剖析,否则为 NaN
。
注:空字符串返回0
。数组 NaN
对象 NaN
-
一个
NaN
与另一个NaN
的比较不会产生true
。 更多信息请参阅“NaN Mozilla 文档”。 -
GitHub 在比较字符串时忽略大小写。
-
对象和数组仅在为同一实例时才视为相等。
函数
GitHub 提供一组内置的函数,可用于表达式。 有些函数抛出值到字符串以进行比较。 GitHub 使用这些转换将数据类型转换为字符串:
类型 | 结果 |
---|---|
Null | '' |
布尔值 | 'true' 或 'false' |
数字 | 十进制� �式,对大数字使用指数 |
数组 | 数组不转换为字符串 |
对象 | 对象不转换为字符串 |
contains
contains( search, item )
如果 search
包含 item
,则返回 true
。 如果 search
为数组,此函数在 item
为数组中的元� 时返回 true
。 如果 search
为字符串,此函数在 item
为 search
的子字符串时返回 true
。 此函数不区分大小写。 抛出值到字符串。
使用数组的示例
contains(github.event.issue.labels.*.name, 'bug')
returns whether the issue related to the event has a label "bug".
使用字符串的示例
contains('Hello world', 'llo')
返回 true
.
startsWith
startsWith( searchString, searchValue )
当 searchString
以 searchValue
开头时返回 true
。 此函数不区分大小写。 抛出值到字符串。
示例
startsWith('Hello world', 'He')
返回 true
.
endsWith
endsWith( searchString, searchValue )
当 searchString
以 searchValue
结尾时返回 true
。 此函数不区分大小写。 抛出值到字符串。
示例
endsWith('Hello world', 'ld')
返回 true
.
format
format( string, replaceValue0, replaceValue1, ..., replaceValueN)
将 string
中的值替换为变量 replaceValueN
。 string
中的变量使用 {N}
语法指定,其中 N
为整数。 必须指定至少一个 replaceValue
和 string
。 可以使用变量 (replaceValueN
) 数没有上限。 使用双小括号逸出大括号。
示例
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(github.event.issue.labels.*.name, ', ')
可能返回 'bug, help wanted'
toJSON
toJSON(value)
对 value
返回适合打印的 JSON 表示形式。 您可以使用此函数调试上下文中提供的信息。
示例
toJSON(job)
可能返回 { "status": "Success" }
fromJSON
fromJSON(value)
返回 value
的 JSON 对象或 JSON 数据类型。 您可以使用此函数来提供 JSON 对象作为评估表达式或从字符串转换环境变量。
返回 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 "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"
job2:
needs: job1
runs-on: ubuntu-latest
strategy:
matrix: ${{fromJSON(needs.job1.outputs.matrix)}}
steps:
- run: build
返回 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 ...
hashFiles
hashFiles(path)
返回匹配 path
模式的文件集的单个哈希值。 您可以提供单一 path
模式,或以逗号分隔的多个 path
模式。 path
相对于 GITHUB_WORKSPACE
目录,只能包括 GITHUB_WORKSPACE
中的文件。 此函数为每个匹配的文件计算单独的 SHA-256 哈希, 然后使用这些哈希来计算文件集的最终 SHA-256 哈希。 有关 SHA-256 的更多信息,请参阅“SHA-2”。
您可以使用模式匹配字符来匹配文件名。 模式匹配在 Windows 上不区分大小写。 有关支持的模式匹配字符的更多信息,请参阅“GitHub Actions 的工作流程语法”。
单一模式示例
匹配仓库中的任何 package-lock.json
文件。
hashFiles('**/package-lock.json')
多个模式示例
为仓库中的任何 package-lock.json
和 Gemfile.lock
文件创建哈希。
hashFiles('**/package-lock.json', '**/Gemfile.lock')
Check Functions
您可以使用以下状态检查函数作为 if
条件中的表达式。 除非您包含其中一个函数,否则 success()
的默认状态检查将会应用。 For more information about if
conditionals, see "Workflow syntax for GitHub Actions".
success
当前面的步骤没有失败或取消时返回 true
。
示例
steps:
...
- name: The job has succeeded
if: ${{ success() }}
always
导致该步骤总是执行,并返回 true
,即使取消也一� �。 作业或步骤在重大故障阻止任务运行时不会运行。 例如,如果获取来源失败。
示例
if: ${{ always() }}
cancelled
在工作流程取消时返回 true
。
示例
if: ${{ cancelled() }}
failure
在作业的任何之前一步失败时返回 true
。 If you have a chain of dependent jobs, failure()
returns true
if any ancestor job fails.
示例
steps:
...
- name: The job has failed
if: ${{ failure() }}
对象过滤器
可以使用 *
语法应用过滤条件并从集合中选择匹配的项目。
例如,考虑名为 fruits
的对象数组。
[
{ "name": "apple", "quantity": 1 },
{ "name": "orange", "quantity": 2 },
{ "name": "pear", "quantity": 1 }
]
过滤条件 fruits.*.name
返回数组 [ "apple", "orange", "pear" ]