我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

GitHub 操作的上下文和表达语法

您可以访问上下文信息并对工作流程和操作中的表达式求值。

GitHub 操作 is available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. 更多信息请参阅“GitHub 的产品。”

本文内容

关于上下文和表达式

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

Expressions are commonly used with the conditional if keyword in a workflow file to determine whether a step should run. 当 if 条件为 true 时,步骤将会运行。

您需要使用特定语法指示 GitHub 对表达式求值,而不是将其视为字符串。

{{ <expression> }}

When you use expressions in an if conditional, you do not need to use the expression syntax ({{ }}) because GitHub automatically evaluates the if conditional as an expression. For more information about if conditionals, see "Workflow syntax for GitHub 操作."

if 条件的示例表达式

steps:
  - uses: actions/hello-world-javascript-action@master
    if: <expression>

设置环境变量的示例

env:
  my_env_var: ${{ <expression> }}

上下文

上下文是一种访问工作流程运行、虚拟环境、作业及步骤相关信息的方式。 上下文使用表达式语法。

{{ <context> }}

上下文名称 类型 描述
github 对象 工作流程运行的相关信息。 更多信息请参阅 github 上下文
env string A step, job, or workflow environment variable.
job 对象 当前执行的作业相关信息。 更多信息请参阅 job 上下文
steps 对象 此作业中已经运行的步骤的相关信息。 更多信息请参阅 steps 上下文
runner 对象 运行当前作业的运行程序相关信息。
secrets 对象 用于访问仓库中设置的密码。 有关密码的更多信息,请参阅“GitHub 操作 的虚拟环境”。
strategy 对象 用于访问配置的策略参数及当前作业的相关信息。 策略参数包括 fail-fastjob-indexjob-totalmax-parallel
matrix 对象 用于访问为当前作业配置的矩阵参数。 例如,如果使用 osnode 版本配置矩阵构建,matrix 上下文对象将包含当前作业的 osnode 版本。

作为表达式的一部分,您可以使用以下两种语法之一访问上下文信息。

  • 索引语法:github['sha']
  • 属性解除参考语法:github.sha

要使用属性解除参考语法,属性名称必须:

  • a-Z_ 开头。
  • 后跟 a-Z 0-9 -_

github 上下文

github 上下文包含有关工作流程运行以及触发运行的事件相关信息。 您可以读取环境变量中的大多数 github 上下文数据。 有关环境变量的更多信息,请参阅“GitHub 操作 的虚拟环境”。

属性名称 类型 描述
github 对象 工作流程中任何作业或步骤期间可用的顶层上下文。
github.event 对象 完整事件 web 挂钩有效负载。 更多信息请参阅“触发工作流程的事件”。
github.workflow string 工作流程的名称。 如果工作流程文件未指定 name,此属性的值将是仓库中工作流程文件的完整路径。
github.actor string 发起工作流程运行的用户的登录名。
github.repository 字符串 所有者和仓库名称。 例如 Codertocat/Hello-World
github.event_name string 触发工作流程运行的事件的名称。
github.sha string 触发工作流程的提交 SHA。
github.ref string 触发工作流程的分支或标记参考。
github.head_ref string 工作流程运行中拉取请求的 head_ref 或来源分支。 此属性仅在触发工作流程运行的事件为 pull_request 时才可用。
github.base_ref 字符串 工作流程运行中拉取请求的 base_ref 或目标分支。 此属性仅在触发工作流程运行的事件为 pull_request 时才可用。

job 上下文

job 上下文包含当前正在运行的作业相关信息。

属性名称 类型 描述
job 对象 此上下文针对工作流程运行中的每项作业而改变。 您可以从作业中的任何步骤访问此上下文。
job.status 字符串 作业的当前状态。 可能的值包括 successfailurecancelled
job.container 对象 作业的容器相关信息。 有关容器的更多信息,请参阅“GitHub 操作 的工作流程语法”。
job.container.network string 容器网络的 id。 运行程序创建作业中所有容器使用的网络。
job.container.id string 容器的 id。
job.services 对象 为作业创建的服务容器。 有关服务容器的更多信息,请参阅“GitHub 操作 的工作流程语法”。
job.services.network string 服务容器网络的 id。 运行程序创建作业中所有容器使用的网络。
job.services.<service id>.id string 服务容器的 id。
job.services.<service id>.ports 对象 容器显露的端口。

steps 上下文

steps 上下文包含当前作业中已经运行的步骤相关信息。

属性名称 类型 描述
steps 对象 此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。
steps.<step id>.outputs 对象 为步骤定义的输出集。 更多信息请参阅“GitHub 操作 的元数据语法”。
steps.<step id>.outputs.<output name> string 特定输出的值。

打印上下文信息到日志文件的示例

要检查每个上下文中可访问的信息,您可以使用此工作流程文件示例。

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-16.04
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

文字

作为表达式的一部分,您可以使用 booleannullnumberstring 数据类型。 Boolean 文字不区分大小写,因此可以使用 trueTrue

数据类型 文字值
boolean truefalse
null null
number JSON 支持的任何数字格式。
字符串 必须使用单引号。 使用单引号逸出文字单引号。

示例

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 使用这些转换将数据类型转换为数字:

    类型 结果
    Null 0
    Boolean true 返回 1
    false 返回 0
    字符串 从任何合法 JSON 数字格式剖析,否则为 NaN
    注:空字符串返回 0
    Array NaN
    对象 NaN
  • 一个 NaN 与另一个 NaN 的比较不会产生 true。 更多信息请参阅“NaN Mozilla 文档”。

  • GitHub 在比较字符串时忽略大小写。

  • 对象和数组仅在为同一实例时才视为相等。

函数

GitHub 提供一组内置的函数,可用于表达式。 有些函数抛出值到字符串以进行比较。 GitHub 使用这些转换将数据类型转换为字符串:

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

contains

contains( searchString, searchValue )

如果 searchString 包含 searchValue,则返回 true。 如果 searchString 为数组,此函数在 searchValue 为数组中的元素时返回 true。 此函数不区分大小写。 抛出值到字符串。

示例

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) 数没有上限。 使用双小括号逸出大括号。

示例

返回 'Hello Mona the Octocat'

format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')

逸出括号示例

返回 '{Hello Mona the Octocat}'

format('{{Hello {0} {1} {2}}}', 'Mona', 'the', 'Octocat')

join

join( element, optionalElem )

element 的值可以是数组或字符串。 element 中的所有值强制转换为字符串。 如果提供 optionalElem,值将附加到 element 末尾。 抛出值到字符串。

使用数组的示例

join(['Hello', 'Mona', 'the'], 'Octocat') 返回 'Hello Mona the Octocat'

使用字符串的示例

join('Hello', 'world!') 返回 'Hello world!'

toJson

toJSON(value)

value 返回适合打印的 JSON 表示形式。 您可以使用此函数调试上下文中提供的信息。

示例

toJSON(job) 可能返回 { "status": "Success" }

hashFiles

hashFiles(path)

Returns a single hash for the set of files that matches the path pattern. The path is relative to the GITHUB_WORKSPACE directory and can only include files inside of the GITHUB_WORKSPACE. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. For more information about SHA-256, see "SHA-2."

You can use pattern matching characters to match file names. Pattern matching is case-insensitive on Windows. For more information about supported pattern matching characters, see "Workflow syntax for GitHub 操作."

示例

Matches any package-lock.json file in the repository.

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

作业状态检查函数

您可以使用以下状态检查函数作为 if 条件中的表达式。 如果 if 表达式不含任何状态函数,将自动返回 success() 结果。 有关 if 条件的更多信息,请参阅“GitHub 操作的工作流程语法”。

success

在作业的上一步成功时返回 true

示例
steps:
  - name: my first step
    if: success()

always

强制条件求值为 true,即使被取消时。 作业或步骤在重大故障阻止任务运行时不会运行。 例如,如果获取来源失败。

示例
if: always()

cancelled

在工作流程取消时返回 true

示例
if: cancelled()

failure

在作业的上一步失败时返回 true

示例
steps:
  - name: my first step
    if: failure()

对象过滤器

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

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

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

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

问问别人

找不到要找的内容?

联系我们