Expressions

You can evaluate expressions in workflows and actions.

注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。

About expressions

您可以使用表达式程序化设置工作流程文件中的变量和访问上下文。 表达式可以是文字值、上下文引用或函数的任意组合。 您可以使用运算符组合文字、上下文引用和函数。 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> }}

文字

作为表达式的一部分,您可以使用 booleannullnumberstring 数据类型。

数据类型文字值
布尔值truefalse
nullnull
numberJSON 支持的任何数字格式。
字符串必须使用单引号。 使用单引号逸出文字单引号。

示例

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99-e2 }}
  myString: ${{ 'Mona the Octocat' }}
  myEscapedString: ${{ 'It''s open source!' }}

运算符

运算符描述
( )逻辑分组
[ ]索引
.属性解除参考
!
<小于
<=小于或等于
>大于
>=大于或等于
==等于
!=不等于
&&
||

GitHub 进行宽松的等式比较。

  • 如果类型不匹配,GitHub 强制转换类型为数字。 GitHub 使用这些转换将数据类型转换为数字:

    类型结果
    Null0
    布尔值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 为字符串,此函数在 itemsearch 的子字符串时返回 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 )

searchStringsearchValue 开头时返回 true。 此函数不区分大小写。 抛出值到字符串。

示例

startsWith('Hello world', 'He') 返回 true.

endsWith

endsWith( searchString, searchValue )

searchStringsearchValue 结尾时返回 true。 此函数不区分大小写。 抛出值到字符串。

示例

endsWith('Hello world', 'ld') 返回 true.

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

string 中的值替换为变量 replaceValueNstring 中的变量使用 {N} 语法指定,其中 N 为整数。 必须指定至少一个 replaceValuestring。 可以使用变量 (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.jsonGemfile.lock 文件创建哈希。

hashFiles('**/package-lock.json', '**/Gemfile.lock')

状态检查函数

您可以使用以下状态检查函数作为 if 条件中的表达式。 除非您包含其中一个函数,否则 success() 的默认状态检查将会应用。 For more information about if conditionals, see "Workflow syntax for GitHub Actions" and "Metadata syntax for GitHub Composite 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() }}

Evaluate Status Explicitly

Instead of using one of the methods above, you can evaluate the status of the job or composite action that is executing the step directly:

Example for workflow step

steps:
  ...
  - name: The job has failed
    if: ${{ job.status == 'failure' }}

This is the same as using if: failure() in a job step.

Example for composite action step

steps:
  ...
  - name: The composite action has failed
    if: ${{ github.action_status == 'failure' }}

This is the same as using if: failure() in a composite action step.

对象过滤器

可以使用 * 语法应用过滤条件并从集合中选择匹配的项目。

例如,考虑名为 fruits 的对象数组。

[
  { "name": "apple", "quantity": 1 },
  { "name": "orange", "quantity": 2 },
  { "name": "pear", "quantity": 1 }
]

过滤条件 fruits.*.name 返回数组 [ "apple", "orange", "pear" ]

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。