表达式_GitHub中文网

关于表达式

您可以使用表达式程序化设置工作流程文件中的环境变量和访问上下文。表达式可以是文字值、上下文引用或函数的任意组合。您可以使用运算符组合文字、上下文引用和函数。有关上下文的详细信息，请参阅“上下文”。

表达式通常与工作流文件中的条件 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`	无需将字符串括在 `${{` 和 `}}` 中。但是，如果这样做，则必须在字符串两边使用单引号 (`'`)。若要使用文本单引号，请使用额外的单引号 (`''`) 转义文本单引号。用双引号 (`"`) 括起来会引发错误。

文本示例

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 在比较字符串时忽略大小写。
steps.<step_id>.outputs.<output_name> 计算为字符串。您需要使用特定语法指示 GitHub 对表达式求值，而不是将其视为字符串。有关详细信息，请参阅“上下文”。
对于数值比较，fromJSON() 函数可用于将字符串转换为数字。有关 fromJSON() 函数的详细信息，请参阅“fromJSON”。

GitHub 进行宽松的等式比较。

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

类型结果
Null 0
布尔 true 返回 1
false 返回 0
String 从任何合法的 JSON 数字格式进行分析，否则为 NaN。
注意：空字符串返回 0。
数组 NaN
对象 NaN
一个 NaN 与另一个 NaN 的比较不会生成 true。有关详细信息，请参阅“NaN Mozilla 文档”。
GitHub 在比较字符串时忽略大小写。
对象和数组仅在为同一实例时才视为相等。

类型	结果
Null	`0`
布尔	`true` 返回 `1` `false` 返回 `0`
String	从任何合法的 JSON 数字格式进行分析，否则为 `NaN`。注意：空字符串返回 `0`。
数组	`NaN`
对象	`NaN`

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。请务必注意，&& 条件后的第一个值必须为 truthy，否则将始终返回 || 后的值。

类型	结果
Null	`''`
布尔	`'true'` 或 `'false'`
数字	十进制格式，对大数字使用指数
数组	数组不转换为字符串
对象	对象不转换为字符串

返回与 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"],
]

由于对象不保留顺序，因此无法保证输出的顺序。

表达式

本文内容