关于变量
可以使用变量来存储要在工作流中引用的信息。 可以在工作流步骤或操作中引用变量,这些变量将在运行工作流的运行器计算机上插值。 在操作或工作流步骤中运行的命令可以创建、读取和修改变量。
可以设置自己的自定义变量,可以使用 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
。 这些变量的值分别在工作流、作业和步骤级别设置和定义作用域。 有关使用上下文访问变量值的详细信息,请参阅“使用上下文访问变量值”。
由于运行器环境变量插值是在将工作流作业发送到运行器计算机后完成的,因此必须对运行器上使用的 shell 使用适当的语法。 在此示例中,工作流指定 ubuntu-latest
。 默认情况下,Linux 运行器使用 bash shell,因此你需要使用语法 $NAME
。 如果工作流指定了 Windows 运行器,那么你应使用 PowerShell 的语法 $env:NAME
。 有关 shell 的详细信息,请参阅“GitHub Actions 的工作流语法”。
环境变量命名约定
设置环境变量时,不能使用任何默认环境变量名称。 有关默认环境变量的完整列表,请参阅下面的“默认环境变量”。 如果尝试重写其中一个默认变量的值,则会忽略赋值。
你设置的指向文件系统上某个位置的任何新变量都应该有 _PATH
后缀。 GITHUB_ENV
和 GITHUB_WORKSPACE
默认变量是此约定的例外情况。
注意:通过在步骤中使用 run: env
并检查此步骤的输出,可以列出可用于工作流步骤的整个环境变量集。
使用上下文访问变量值
上下文是一种访问工作流运行、变量、运行器环境、作业及步骤相关信息的方式。 有关详细信息,请参阅“上下文”。 在工作流程中,还有许多其他上下文可用于各种目的。 有关可在工作流中使用特定上下文的位置的详细信息,请参阅“上下文”。
可以使用 env
上下文来访问环境变量值。
使用 env
上下文访问环境变量值
除了运行器环境变量之外,GitHub Actions 还允许使用上下文设置和读取 env
键值。 环境变量和上下文旨在用于工作流程中的不同点。
运行器环境变量始终在运行器计算机上插值。 但是,工作流程的某些部分由 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
条件语句中访问此值。
注意:上下文通常使用美元符号和大括号表示,例如 ${{ context.property }}
。 在 if
条件中,${{
和 }}
是可选的,但如果使用它们,它们必须括住整个比较语句,如上所示。
你通常将使用 env
或 github
上下文来访问工作流部分中的变量值,这些值是在作业发送给运行器之前处理的。
上下文 | 使用案例 | 示例 |
---|---|---|
env | 引用工作流中定义的自定义变量。 | ${{ env.MY_VARIABLE }} |
github | 引用有关工作流程运行的信息和触发运行的事件。 | ${{ github.repository }} |
默认环境变量
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。 例如:https://HOSTNAME/api/v3 。 |
GITHUB_BASE_REF | 工作流运行中拉取请求的基本引用或目标分支的名称。 仅当触发工作流运行的事件是 pull_request 或 pull_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。 例如:https://HOSTNAME/api/graphql 。 |
GITHUB_HEAD_REF | 工作流运行中拉取请求的头部引用或来源分支。 仅当触发工作流运行的事件是 pull_request 或 pull_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 。 |
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_URL | GitHub AE 服务器的 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_WORKFLOW | 工作流的名称。 例如 My test workflow 。 如果工作流文件未指定 name ,则此变量的值是存储库中工作流文件的完整路径。 |
GITHUB_WORKSPACE | 运行器上步骤的默认工作目录,以及使用 checkout 操作时存储库的默认位置。 例如 /home/runner/work/my-repo-name/my-repo-name 。 |
RUNNER_ARCH | 执行作业的运行器的体系结构。 可能的值为 X86 、X64 、ARM 或 ARM64 。 |
RUNNER_DEBUG | 仅当启用调试日志记录并且始终具有值 1 时,才会进行此设置。 它可以用作指示器,以便在自己的作业步骤中启用更多调试或详细日志记录。 |
RUNNER_NAME | 执行作业的运行器的名称。 例如,Hosted Agent |
RUNNER_OS | 执行作业的运行器的操作系统。 可能的值为 Linux 、Windows 或 macOS 。 例如,Windows |
RUNNER_TEMP | 运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。 例如,D:\a\_temp |
注意****:如果需要在工作中使用工作流运行的 URL,可以组合以下变量:$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
检测操作系统
通过使用 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 的工作流语法”。