在变量中存储信息

关于变量

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

您可以设置您自己的自定义变量或使用 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命令中使用：$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 的工作流语法”。

环境变量的命名约定

设置环境变量时，您不能使用任何默认环境变量名称。有关默认环境变量的完整列表，请参阅下面“默认环境变量”。如果您尝试覆盖这些默认变量之一的值，则该赋值将被忽略。

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

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

例如，您可以使用配置变量在组织级别为传递给构建工具的参数设置默认值，然后允许仓库所有者根据具体情况覆盖这些参数。

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

配置变量优先级

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

对于可复用的工作流，将使用调用者工作流仓库中的变量。包含被调用工作流的仓库中的变量不会提供给调用者工作流。

配置变量的命名约定

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

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

为仓库创建配置变量

要在 GitHub 上为个人帐户仓库创建密钥或变量，您必须是仓库所有者。要在 GitHub 上为组织仓库创建密钥或变量，您必须具有admin访问权限。最后，要通过 REST API 为个人帐户仓库或组织仓库创建密钥或变量，您必须具有协作者访问权限。

1. 在 GitHub 上，导航到仓库的主页。

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

   

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

4. 单击变量选项卡。

   

5. 单击新建仓库变量。

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

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

8. 单击添加变量。

为环境创建配置变量

要在个人帐户仓库中为环境创建密钥或变量，您必须是仓库所有者。要在组织仓库中为环境创建密钥或变量，您必须具有admin访问权限。有关环境的更多信息，请参阅“管理部署环境”。

1. 在 GitHub 上，导航到仓库的主页。

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

   

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

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

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

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

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

8. 单击添加变量。

为组织创建配置变量

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

组织所有者可以在组织级别创建密钥或变量。

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

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

   

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

4. 单击变量选项卡。

   

5. 单击新建组织变量。

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

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

8. 从仓库访问下拉列表中，选择访问策略。

9. 单击添加变量。

配置变量的限制

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

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

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

• 最多 500 个仓库变量，如果仓库变量的总大小小于 256 KB。如果仓库变量的总大小超过 256 KB，则只有低于限制的仓库变量可用（按变量名称字母顺序排序）。
• 最多 1,000 个组织变量，如果仓库和组织变量的总组合大小小于 256 KB。如果组织和仓库变量的总组合大小超过 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条件语句中使用上下文来访问变量的值。

name: Conditional env variable

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"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

name: Conditional env variable

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"
        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 而异），就可以成功运行以下工作流。

on: workflow_dispatch

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."

on: workflow_dispatch

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