Skip to main content

环境变量

GitHub 为每个 GitHub Actions 工作流程运行设置默认环境变量。 您也可以在工作流程文件中设置自定义环境变量。

注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。

关于环境变量

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

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

要设置自定义环境变量,必须在工作流程文件中定义它。 自定义环境变量的作用域仅限于在其中定义它的元素。 您可以定义作用域如下的环境变量:

  • 整个工作流程,通过使用 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

上面的示例显示了在 echo 命令中使用的三个自定义环境变量:$DAY_OF_WEEK$Greeting$First_Name。 这些环境变量的值分别在工作流程、作业和步骤级别设置和定义作用域。

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

注意:您可以在步骤中使用 run: env ,然后检查步骤的输出,以列出可用于工作流程步骤的整个环境变量集。

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

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

环境变量始终在虚拟机运行器上插值。 但是,工作流程的某些部分由 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

在第一个示例的修改中,我们引入了 if 条件。 现在,工作流程步骤仅在 DAYS_OF_WEEK 设置为 "Monday" 时才会运行。 我们通过使用 env contextif 语句访问此值。

注意:上下文通常使用美元符号和大括号表示,如 ${{ context.property }}。 在 if 条件中,${{ and }} 是可选的,但如果使用它们,它们必须括住整个比较语句,如上所示。

您通常使用 envgithub 上下文来访问工作流程部分中的环境变量值,这些值在作业发送给运行器之前处理。

上下文用例示例
env引用工作流中定义的自定义环境变量。${{ env.MY_VARIABLE }}
github引用有关工作流程运行的信息和触发运行的事件。${{ github.repository }}

在工作流程中,还有许多其他上下文可用于各种目的。 更多信息请参阅“上下文”。 有关您可以在工作流程中使用特定上下文的详细信息,请参阅“上下文可用性”。

其他类型的变量

在工作流程中的大多数位置,可以使用的唯一变量类型是环境变量,如 $MY_VARIABLE,或等效的上下文属性,如 '${{ env.MY_VARIABLE }}'。 例外情况包括:

  • workflow_callworkflow_dispatch 事件的输入,允许您将值传递到工作流程。 更多信息请参阅 on.workflow_call.inputson.workflow_dispatch.inputs
  • 作业输出,允许您在工作流程中的作业之间传递值。 更多信息请参阅 jobs.<job_id>.outputs
  • 格式表达式中的变量,允许您替换字符串的某些部分。 更多信息请参阅 format

环境变量命名约定

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

您设置的指向文件系统上某个位置的任何新环境变量都应该有 _PATH 后缀。 HOMEGITHUB_ENVGITHUB_WORKSPACE 默认环境变量是此约定的例外。

默认环境变量

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

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

环境变量描述
CI始终设置为 true
GITHUB_ACTION当前运行的操作的名称,或步骤的 id。 例如,对于操作 __repo-owner_name-of-action-repo

GitHub 将删除特殊字符,并在当前步骤运行没有 ID的脚本时使用名称 __run。 如果在同一作业中多次使用相同的脚本或操作,则名称将包含一个由序号前跟下划线组成的后缀。 例如,运行的第一个脚本名称 __run,则第二个脚本将命名为 __run_2。 同样,actions/checkout 第二次调用时将变成 actionscheckout2
GITHUB_ACTION_PATH操作所在的路径。 此属性仅在复合操作中受支持。 您可以使用此路径访问与操作位于同一存储库中的文件。 例如,/home/runner/work/_actions/repo-owner/name-of-action-repo/v1
GITHUB_ACTION_REPOSITORY对于执行操作的步骤,这是操作的所有者和存储库名称。 例如 actions/checkout
GITHUB_ACTIONS当 GitHub Actions 运行工作流程时,始终设置为 true。 您可以使用此变量来区分测试是在本地运行还是通过 GitHub Actions 运行。
GITHUB_ACTOR发起工作流程的个人或应用程序的名称。 例如 octocat
GITHUB_API_URL返回 API URL。 例如:http(s)://[hostname]/api/v3
GITHUB_BASE_REF工作流程运行中拉取请求的基本引用或目标分支的名称。 这仅在触发工作流运行的事件 pull_requestpull_request_target 时才会设置。 例如 main
GITHUB_ENV运行器上从工作流程命令到设置环境变量的文件路径。 此文件对于当前步骤是唯一的,并且会针对作业中的每个步骤进行更改。 例如,/home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a。 更多信息请参阅“GitHub Actions 的工作流程命令”。
GITHUB_EVENT_NAME触发工作流程的事件的名称。 例如,workflow_dispatch
GITHUB_EVENT_PATH运行器上包含完整事件 web 挂钩负载的文件的路径。 例如 /github/workflow/event.json
GITHUB_GRAPHQL_URL返回 GraphQL API URL。 例如:http(s)://[hostname]/api/graphql
GITHUB_HEAD_REF工作流程运行中拉取请求的头部引用或来源分支。 此属性仅在触发工作流程运行的事件为 pull_requestpull_request_target 时才设置。 例如,feature-branch-1
GITHUB_JOB当前作业的 job_id。 例如,greeting_job
GITHUB_PATH运行器上从工作流程命令到设置系统 PATH 变量的文件路径。 此文件对于当前步骤是唯一的,并且会针对作业中的每个步骤进行更改。 例如 /home/runner/work/_temp/_runner_file_commands/add_path_899b9445-ad4a-400c-aa89-249f18632cf5。 更多信息请参阅“GitHub Actions 的工作流程命令”。
GITHUB_REF触发工作流程的分支或标记参考。 For workflows triggered by push, this is the branch or tag ref that was pushed. For workflows triggered by pull_request, this is the pull request merge branch. For workflows triggered by release, this is the release tag created. For other triggers, this is the branch or tag ref that triggered the workflow run. This is only set if a branch or tag is available for the event type. The ref given is fully-formed, meaning that for branches the format is refs/heads/<branch_name>, for pull requests it is refs/pull/<pr_number>/merge, and for tags it is refs/tags/<tag_name>. 例如 refs/heads/feature-branch-1
GITHUB_REF_NAME触发工作流程的分支或标记名称。 For example, feature-branch-1.
GITHUB_REPOSITORY所有者和存储库名称。 例如 octocat/Hello-World
GITHUB_WORKFLOW工作流程的名称。 例如 My test workflow。 如果工作流程文件未指定名称,则此变量的值是存储库中工作流程文件的完整路径。
RUNNER_ARCH执行作业的运行器的架构。 可能的值包括 X86X64ARMARM64
RUNNER_DEBUGThis is set only if debug logging is enabled, and always has the value of 1. It can be useful as an indicator to enable additional debugging or verbose logging in your own job steps.
RUNNER_TOOL_CACHE包含 GitHub 托管运行器预安装工具的目录路径。 更多信息请参阅“关于 GitHub 托管的运行器”。 例如 C:\hostedtoolcache\windows

注:

  • 如果需要在作业中使用工作流程运行的 URL,您可以组合这些环境变量:$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
  • 大多数默认环境变量都有一个对应且名称类似的上下文属性。 例如,在工作流程处理期间,可以使用 ${{ github.ref }} 上下文属性读取 GITHUB_REF 环境变量的值。

检测操作系统

通过使用默认环境变量和相应的上下文属性 ${{ 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."

在此示例中,两个 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 环境文件。 环境文件可由操作直接使用,也可从工作流程文件中的 shell 命令使用 run 关键字。 更多信息请参阅“GitHub Actions 的工作流程命令”。

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