变量

关于变量

变量提供了一种存储和重用非敏感配置信息的方法。 可以将任何配置数据（如编译器标志、用户名或服务器名称）存储为变量。 变量在运行工作流的运行器计算机上插值。 在操作或工作流步骤中运行的命令可以创建、读取和修改变量。

可以设置自己的自定义变量，也可以使用 GitHub 自动设置的默认环境变量。 有关详细信息，请参阅“默认环境变量”。

可以通过两种方式设置自定义变量。

• 若要定义要在单个工作流中使用的环境变量，可以在工作流文件中使用 env 键。 有关详细信息，请参阅“为单个工作流定义环境变量”。
• 若要跨多个工作流定义配置变量，可以在组织、存储库或环境级别定义它。 有关详细信息，请参阅“为多个工作流定义配置变量”。

为单个工作流定义环境变量

若要为单个工作流设置自定义环境变量，可以在工作流文件中使用 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 默认变量是此约定的例外情况。

为多个工作流定义配置变量

可以创建用于多个工作流的配置变量，并且可以在组织、存储库或环境级别定义它们。

例如，可以使用配置变量为传递给组织级别的生成工具的参数设置默认值，但随后允许存储库所有者根据具体情况重写这些参数。

定义配置变量时，它们在 vars 上下文中自动可用。 有关详细信息，请参阅“使用 vars 上下文访问配置变量值”。

配置变量优先级

如果具有相同名称的变量存在于多个级别，则级别最低的变量优先。 例如，如果组织级别变量的名称与存储库级别的变量相同，则存储库级别的变量优先。 同样，如果组织、存储库和环境都具有同名的变量，则环境级变量优先。

对于可重用工作流，将使用调用方工作流存储库中的变量。 存储库中包含被调用工作流的变量不可用于调用方工作流。

配置变量的命名约定

以下规则适用于配置变量名称：

• 名称只能包含字母数字字符（[a-z]、[A-Z]、[0-9]）或下划线 (_)。 不允许空格。
• 名称不能以 GITHUB_ 前缀开头。
• 名称不能以数字开头。
• 名称不区分大小写。
• 名称在所创建的级别上必须是唯一的。

为存储库创建配置变量

若要在 GitHub 上为个人帐户存储库创建机密或变量，你必须是存储库所有者。 若要在 GitHub 上为组织存储库创建机密或变量，你必须拥有 admin 访问权限。 最后，若要通过 REST API 为个人帐户存储库或组织存储库创建机密或变量，你必须拥有协作者访问权限。

1. 在 GitHub.com 上，导航到存储库的主页。

2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。

   

3. 在边栏的“安全性”部分中，选择“ 机密和变量”、然后单击“操作” 。

4. 单击“变量”选项卡。

5. 单击“新建存储库变量”。

6. 在“名称”字段中输入变量的名称。

7. 在“值”字段中输入变量的值。

8. 单击“添加变量”。

为环境创建配置变量

若要在个人帐户存储库中为某个环境创建机密或变量，你必须是存储库所有者。 若要在组织存储库中为某个环境创建机密或变量，你必须拥有 admin 访问权限。 有关环境的详细信息，请参阅“使用环境进行部署”。

1. 在 GitHub.com 上，导航到存储库的主页。

2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。

   

3. 在左侧边栏中，单击“环境”。

4. 单击要向其添加变量的环境。

5. 在“环境变量”下，单击“添加变量” 。

6. 在“名称”字段中输入变量的名称。

7. 在“值”字段中输入变量的值。

8. 单击“添加变量”。

为组织创建配置变量

在组织中创建机密或变量时，可以使用策略来限制存储库的访问。 例如，您可以将访问权限授予所有仓库，也可以限制仅私有仓库或指定的仓库列表拥有访问权限。

要在组织级别创建机密或变量，你必须是组织所有者。

1. 在 GitHub.com 上，导航到组织的主页。

2. 在组织名称下，单击 “设置”****。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。

   

3. 在边栏的“安全性”部分中，选择“ 机密和变量”、然后单击“操作” 。

4. 单击“变量”选项卡。

   

5. 单击“新建组织变量”。

6. 在“名称”字段中输入变量的名称。

7. 在“值”字段中输入变量的值。

8. 从“存储库访问”下拉列表中，选择访问策略。

9. 单击“添加变量”。

配置变量的限制

单个变量大小限制为 48 KB。

最多可以存储 1,000 个组织变量、每个存储库 500 个变量和每个环境 100 个变量。 组织和存储库变量的总大小限制为每个工作流运行 256 KB。

在存储库中创建的工作流可以访问以下数量的变量：

• 如果存储库变量的总大小小于 256 KB，则最多 500 个存储库变量。 如果存储库变量的总大小超过 256 KB，则只有低于限制的存储库变量才可用（按变量名称的字母顺序排序）。
• 如果存储库和组织变量的总大小小于 256 KB，则最多 1,000 个组织变量。 如果组织和存储库变量的总大小超过 256 KB，则只有低于该限制的组织变量将可用（在考虑存储库变量并按变量名称的字母顺序排序后）。
• 最多 100 个环境级别变量。

使用上下文访问变量值

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

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

使用 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 上下文来访问工作流部分中的变量值，这些值是在作业发送给运行器之前处理的。

使用 vars 上下文访问配置变量值

可以使用 vars 上下文在整个工作流中访问配置变量。 有关详细信息，请参阅“上下文”。

如果尚未设置配置变量，则引用该变量的上下文的返回值将为空字符串。

以下示例演示如何在工作流中将配置变量与 vars 上下文配合使用。 以下每个配置变量都已在存储库、组织或环境级别上定义。

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

默认环境变量

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 的工作流语法”。