Skip to main content

此版本的 GitHub Enterprise Server 将于以下日期停止服务 2023-12-20. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

变量

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

注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

关于变量

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

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

定义环境变量

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

YAML
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_ENVGITHUB_WORKSPACE 默认变量是此约定的例外情况。

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

使用上下文访问变量值

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

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

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

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

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

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

YAML
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 }}!"

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

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

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

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

默认环境变量

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

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

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

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

变量说明
CI始终设置为 true
GITHUB_ACTION正在运行的操作的名称,或步骤的 id。 例如,对于操作,为 __repo-owner_name-of-action-repo

在当前步骤运行不带 id 的脚本时,GitHub 会删除特殊字符并使用名称 __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_OUTPUT运行器上通过工作流命令设置当前步骤输出的文件的路径。 此文件对于当前步骤是唯一的,并且会针对作业中的每个步骤进行更改。 例如 /home/runner/work/_temp/_runner_file_commands/set_output_a50ef383-b063-46d9-9157-57953fc9f3f0。 有关详细信息,请参阅“GitHub Actions 的工作流命令”。
GITHUB_PATH运行器上从工作流命令设置系统 PATH 变量的文件的路径。 此文件对于当前步骤是唯一的,并且会针对作业中的每个步骤进行更改。 例如 /home/runner/work/_temp/_runner_file_commands/add_path_899b9445-ad4a-400c-aa89-249f18632cf5。 有关详细信息,请参阅“GitHub Actions 的工作流命令”。
GITHUB_REF触发工作流运行的分支或标记的格式完整的参考。 对于 push 触发的工作流,这是推送的分支或标记参考。 对于 pull_request 触发的工作流,这是拉取请求合并分支。 对于 release 触发的工作流,这是创建的发布标记。 对于其他触发器,这是触发工作流运行的分支或标记参考。 此变量仅在分支或标记可用于事件类型时才会设置。 给定的参考格式完整,这意味着对于分支,其格式为 refs/heads/<branch_name>,对于拉取请求,其格式为 refs/pull/<pr_number>/merge,对于标签,其格式为 refs/tags/<tag_name>。 例如,refs/heads/feature-branch-1
GITHUB_REF_NAME触发工作流运行的分支或标记的短参考名称。 此值与 GitHub 上显示的分支或标记名称匹配。 例如 feature-branch-1

拉取请求的格式为 refs/pull/<pr_number>/merge
GITHUB_REF_PROTECTED如果为触发工作流运行的 ref 配置分支保护 ,则为 true
GITHUB_REF_TYPE触发工作流运行的 ref 类型。 有效值为 branch or tag进行求值的基于 SQL 语言的筛选器表达式。
GITHUB_REPOSITORY所有者和存储库名称。 例如 octocat/Hello-World
GITHUB_REPOSITORY_OWNER存储库所有者的名称。 例如 octocat
GITHUB_RETENTION_DAYS工作流运行日志和项目保留的天数。 例如 90
GITHUB_RUN_ATTEMPT存储库中每次尝试运行特定工作流的唯一编号。 对于工作流程运行的第一次尝试,此数字从 1 开始,并随着每次重新运行而递增。 例如 3
GITHUB_RUN_ID存储库中每个工作流运行的唯一编号。 如果您重新执行工作流程运行,此编号不变。 例如 1658821493
GITHUB_RUN_NUMBER仓库中特定工作流程每个运行的唯一编号。 工作流首次运行时,此编号从 1 开始,并随着每次新的运行而递增。 如果您重新执行工作流程运行,此编号不变。 例如 3
GITHUB_SERVER_URLGitHub Enterprise Server 服务器的 URL。 例如:https://HOSTNAME
GITHUB_SHA触发工作流的提交 SHA。 此提交 SHA 的值取决于触发工作流程的事件。 有关详细信息,请参阅“触发工作流的事件”。 例如,ffac537e6cbbf934b08745a378932722df287a53
GITHUB_STEP_SUMMARY运行器上包含来自工作流命令的作业摘要的文件的路径。 此文件对于当前步骤是唯一的,并且会针对作业中的每个步骤进行更改。 例如 /home/runner/_layout/_work/_temp/_runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c。 有关详细信息,请参阅“GitHub Actions 的工作流命令”。
GITHUB_TRIGGERING_ACTORThe username of the user that initiated the workflow run. If the workflow run is a re-run, this value may differ from github.actor. Any workflow re-runs will use the privileges of github.actor, even if the actor initiating the re-run (github.triggering_actor) has different privileges.
GITHUB_WORKFLOW工作流的名称。 例如 My test workflow。 如果工作流文件未指定 name,则此变量的值是存储库中工作流文件的完整路径。
GITHUB_WORKSPACE运行器上步骤的默认工作目录,以及使用 checkout 操作时存储库的默认位置。 例如 /home/runner/work/my-repo-name/my-repo-name
RUNNER_ARCH执行作业的运行器的体系结构。 可能的值为 X86X64ARMARM64
RUNNER_DEBUG仅当启用调试日志记录并且始终具有值 1 时,才会进行此设置。 它可以用作指示器,以便在自己的作业步骤中启用更多调试或详细日志记录。
RUNNER_NAME执行作业的运行器的名称。 此名称在工作流运行中可能并不唯一,因为存储库和组织级别的运行器可以使用同一名称。 例如,Hosted Agent
RUNNER_OS执行作业的运行器的操作系统。 可能的值为 LinuxWindowsmacOS。 例如,Windows
RUNNER_TEMP运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。 例如,D:\a\_temp
RUNNER_TOOL_CACHE包含 GitHub 托管运行器预安装工具的目录路径。 有关详细信息,请参阅“使用 GitHub 托管的运行器”。 例如,C:\hostedtoolcache\windows

注意****:如果需要在工作中使用工作流运行的 URL,可以组合以下变量:$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID

检测操作系统

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

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