浏览 GitHub 中的上下文和表达式

已完成

上下文是访问有关工作流运行、变量、运行程序环境、作业和步骤的信息的方法。 每个上下文都是一个包含属性的对象,可以是字符串或其他对象。

可以使用表达式语法访问上下文。 表达式可以是文本值、对上下文或函数的引用的任意组合。 可以使用运算符组合文本、上下文引用和函数。

上下文

创建工作流和作时,应始终考虑代码是否可能执行可能攻击者的不受信任的输入。 某些上下文应被视为不受信任的输入,因为攻击者可以插入自己的恶意内容。 有关详细信息,请访问 GitHub Actions的安全强化。

下表包含 GitHub 中可用的上下文示例,它不是完整的列表。

上下文名称 类型 描述
github object 有关工作流运行的信息。
env object 包含工作流、作业或步骤中设置的变量。
vars object 包含存储库、组织或环境级别设置的变量。
job object 有关当前运行的作业的信息。

提示

有关上下文的完整列表,请访问关于上下文。

确定何时使用上下文

GitHub Actions 包括两个称为“默认变量”和“上下文”的变量集合。 这些变量适用于工作流中的不同点:

  • 默认环境变量:这些环境变量仅存在于正在执行作业的运行程序上。
  • 上下文:在工作流的任意时间点,你可以使用大多数上下文,即使 默认变量 不可用时。

在以下示例中,if 语句检查 github.ref 上下文以确定当前分支名称。 将处理 if 检查,并且仅当结果为 true 时,作业才会发送到运行程序。 将作业发送到运行程序后,将执行该步骤,并引用运行程序中的 $GITHUB_REF 变量。

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

GitHub Actions 中可用的上下文

下表包含可用的顶级上下文、简要说明和有关对象属性的详细信息的链接。

顶层上下文 描述 属性和示例
github 工作流中的任何作业或步骤中可用的顶级上下文。 github上下文的属性。
env 包含工作流、作业或步骤中设置的变量。 它不包含运行程序进程继承的变量。 env上下文的属性。
vars 包含组织、存储库和环境级别设置的自定义配置变量。 vars用法示例。
job 包含有关当前运行的作业的信息。 job上下文的属性。
jobs 仅在可重用工作流中可用,并且只能用于设置可重用工作流的输出。 jobs上下文的属性。
steps 包含有关当前作业中已指定 id 的已完成步骤的信息。 steps上下文的属性。
runner 包含有关正在执行当前作业的运行程序的信息。 runner上下文的属性。
secrets 包含可用于工作流运行的机密的名称和值。 secrets上下文的属性。
strategy 包含有关当前作业的矩阵执行策略的信息。 strategy上下文的属性。
matrix 包含应用于当前作业的工作流文件中定义的矩阵属性。 matrix上下文的属性。
needs 包含定义为当前作业的直接依赖项的所有作业的输出。 matrix上下文的属性。
inputs 包含传递给操作、可重用工作流或手动触发的工作流的输入属性。 inputs上下文的属性。

表达 式

可以使用表达式以编程方式在工作流文件和访问上下文中设置环境变量。 表达式可以是文本值、对上下文或函数的引用的任意组合。 可以使用运算符组合文本、上下文引用和函数。

表达式通常与工作流文件中的条件 if 关键字一起使用,以确定是否应运行步骤。 if 条件为 true 时,将运行该步骤。

需要使用特定语法 ${{ <expression> }}来告诉 GitHub 计算表达式,而不是将其视为字符串。 此规则的例外情况是在 if 子句中使用表达式时,通常可以省略 ${{ 和 }}。

下面的代码示例演示如何设置环境变量。

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

文本

作为表达式的一部分,可以使用 boolean、null、number或 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!' }}

运营商

运算符在计算表达式方面发挥了关键作用。 表达式可以包含文本值、对上下文的引用或函数。 使用运算符可以合并这些元素来创建更复杂的表达式。 下面是一些关键运算符:

  • 逻辑运算符:

    • &&(和):合并两个条件,这两个条件都必须为 true,以便整体表达式的计算结果为 true。
    • ||(或):合并两个条件,如果任一条件为 true,表达式的计算结果为 true。
    • !(非):否定条件,翻转其真值。
  • 相等运算符:

    • ==(等于):比较两个相等值。
    • !=(不相等):检查两个值是否不相等。
  • 比较运算符:

    • < (小于)
    • > (大于)
    • <=(小于或等于)
    • >=(大于或等于)

这些运算符允许你通过确定何时应根据条件运行特定步骤来创建动态工作流。 请务必对表达式(如 $\{\{ <expression> \}\}$)使用正确的语法来确保正确计算。

有关运算符的详细信息,请访问运算符。