变量

关于变量

可以使用变量来存储要在工作流中引用的信息。 可以在工作流步骤或操作中引用变量，这些变量将在运行工作流的运行器计算机上插值。 在操作或工作流步骤中运行的命令可以创建、读取和修改变量。

可以设置自己的自定义变量，可以使用 GitHub 自动设置的默认变量，还可以使用在运行器上的工作环境中设置的任何其他变量。 变量区分大小写。

定义环境变量

若要设置自定义环境变量，可以在工作流文件中使用 env 键对其进行定义。 此方法设置的自定义变量的作用域仅限于在其中定义它的元素。 可以定义作用域如下的变量：

• 整个工作流，方法是在工作流文件的顶层使用 env。
• 工作流中的作业内容，方法是使用 jobs.<job_id>.env。
• 作业中的特定步骤，方法是使用 jobs.<job_id>.steps[*].env。

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

可以使用运行器环境变量或上下文访问 env 变量值。 上面的示例显示了要在 echo 命令中用作运行器环境变量的 3 个自定义变量：$DAY_OF_WEEK、$Greeting 和 $First_Name。 这些变量的值分别在工作流、作业和步骤级别设置和定义作用域。 这些变量的内插发生在运行器上。

工作流或引用操作 run 步骤中的命令由在运行器上使用的 shell 处理。 工作流其他部件中的指令由 GitHub Actions 处理，不会发送到运行器。 可以在 run 步骤中使用运行器环境变量或上下文，但在未发送到运行器的工作流部件中，必须使用上下文来访问变量值。 有关详细信息，请参阅“使用上下文访问变量值”。

由于运行器环境变量插值是在将工作流作业发送到运行器计算机后完成的，因此必须对运行器上使用的 shell 使用适当的语法。 在此示例中，工作流指定 ubuntu-latest。 默认情况下，Linux 运行器使用 bash shell，因此你需要使用语法 $NAME。 Windows 运行器默认使用 PowerShell，因此您将使用语法 $env:NAME。 有关 shell 的详细信息，请参阅“GitHub Actions 的工作流语法”。

环境变量命名约定

设置环境变量时，不能使用任何默认环境变量名称。 有关默认环境变量的完整列表，请参阅下面的“默认环境变量”。 如果尝试重写其中一个默认变量的值，则会忽略赋值。

你设置的指向文件系统上某个位置的任何新变量都应该有 _PATH 后缀。 GITHUB_ENV 和 GITHUB_WORKSPACE 默认变量是此约定的例外情况。

使用上下文访问变量值

上下文是一种访问工作流运行、变量、运行器环境、作业及步骤相关信息的方式。 有关详细信息，请参阅“上下文”。 在工作流程中，还有许多其他上下文可用于各种目的。 有关可在工作流中使用特定上下文的位置的详细信息，请参阅“上下文”。

可以使用 env 上下文来访问环境变量值。

使用 env 上下文访问环境变量值

除了运行器环境变量之外，GitHub Actions 还允许使用上下文设置和读取 env 键值。 环境变量和上下文旨在用于工作流程中的不同点。

工作流或引用操作中的 run 步骤由运行器处理。 因此，可以使用此处的运行器环境变量，对运行器上使用的 shell 使用适当的语法（例如，Linux 运行器上的 bash shell 使用 $NAME，Windows 运行器上的 PowerShell 使用 $env:NAME）。 在大多数情况下，还可以使用语法为 ${{ CONTEXT.PROPERTY }} 的上下文来访问相同的值。 区别在于，在作业发送到运行器之前，上下文将被内插并替换为字符串。

但是，在由 GitHub Actions 处理且不会发送到运行器的工作流部件中，无法使用运行器环境变量。 相反，您必须使用上下文。 例如，if 条件（用于确定作业或步骤是否发送到运行器）始终由 GitHub Actions 处理。 必须在 if 条件语句中使用上下文访问变量的值。

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

在前面的示例的此修改中，我们引入了 if 条件。 工作流步骤现在仅当 DAY_OF_WEEK 设置为“Monday”时才运行。 我们使用 env 上下文从 if 条件语句中访问此值。 run 命令中引用的变量不需要 env 上下文。 这些变量被引用为运行器环境变量，并在运行器收到作业后进行内插。 不过，可以选择在将作业发送到运行器之前，通过使用上下文内插这些变量。 输出结果相同。

run: echo "${{ env.Greeting }} ${{ env.First_Name }}. Today is ${{ env.DAY_OF_WEEK }}!"

你通常将使用 env 或 github 上下文来访问工作流部分中的变量值，这些值是在作业发送给运行器之前处理的。

默认环境变量

GitHub 设置的默认环境变量可用于工作流程中的每个步骤。

由于默认环境变量由 GitHub 设置，并且未在工作流中进行定义，因此无法通过 env 上下文访问它们。 但是，大多数默认变量都有一个对应且名称类似的上下文属性。 例如，在工作流处理期间，可以使用 ${{ github.ref }} 上下文属性读取 GITHUB_REF 变量的值。

不能覆盖名为 GITHUB_* 和 RUNNER_* 的默认环境变量的值。 目前可以覆盖 CI 变量的值。 但是，并不能保证这总是可行。 有关设置环境变量的详细信息，请参阅“为单个工作流定义环境变量”和“GitHub Actions 的工作流命令”。

强烈建议操作使用变量访问文件系统，而非使用硬编码的文件路径。 GitHub 设置供操作用于所有运行器环境中的变量。

检测操作系统

通过使用 RUNNER_OS 默认环境变量和相应的上下文属性 ${{ runner.os }}，可以编写可用于不同操作系统的单个工作流文件。 例如，如果将操作系统从 macos-latest 更改为 windows-latest，以下工作流可以成功运行，而不必更改环境变量的语法，这会根据运行器使用的 shell 而有所不同。

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

在此示例中，两个 if 语句会检查 runner 上下文的 os 属性以确定运行器的操作系统。 if 条件由 GitHub Actions 处理，并且只有检查解析为 true 的步骤才会发送到运行器。 这里其中一个检查将始终为 true，而另一个检查为 false，因此只有其中一个步骤会发送到运行器。 在作业发送到运行器后，将执行该步骤，并使用适当的语法（在 Windows 上针对 PowerShell 使用 $env:NAME，在 Linux 和 MacOS 上针对 bash 和 sh 使用 $NAME）对 echo 命令中的环境变量进行内插。 在此示例中，语句 runs-on: macos-latest 表示将运行第二个步骤。

在工作流程中的步骤和作业之间传递值

如果在作业的某个步骤中生成值，则可以在同一作业的后续步骤中使用该值，方法是将该值分配给现有或新的环境变量，然后将其写入 GITHUB_ENV 环境文件。 环境文件可由操作直接使用，也可以通过使用 run 关键字在工作流文件中通过 shell 命令使用。 有关详细信息，请参阅“GitHub Actions 的工作流命令”。

如果要将工作流程中一个作业的某个步骤中的值传递到工作流程中另一作业的某个步骤，可以将该值定义为作业输出。 然后，可以从另一个作业中的步骤引用此作业输出。 有关详细信息，请参阅“GitHub Actions 的工作流语法”。