上下文

You can access context information in workflows and actions.

About contexts

警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。

上下文是一种访问工作流程运行、运行器环境、作业及步骤相关信息的方式。 上下文使用表达式语法。 For more information, see "Expressions."

${{ <context> }}

上下文名称类型描述
github对象工作流程运行的相关信息。 更多信息请参阅 github 上下文
env对象包含工作流程、作业或步骤中设置的环境变量。 更多信息请参阅 env 上下文
job对象当前执行的作业相关信息。 更多信息请参阅 job 上下文
steps对象此作业中已经运行的步骤的相关信息。 更多信息请参阅 steps 上下文
runner对象运行当前作业的运行程序相关信息。 更多信息请参阅 runner 上下文
secrets对象启用对密码的访问权限。 有关密码的更多信息,请参阅“创建和使用加密密码”。
strategy对象用于访问配置的策略参数及当前作业的相关信息。 策略参数包括 fail-fastjob-indexjob-totalmax-parallel
matrix对象用于访问为当前作业配置的矩阵参数。 例如,如果使用 osnode 版本配置矩阵构建,matrix 上下文对象将包含当前作业的 osnode 版本。
needs对象允许访问定义为当前作业依赖项的所有作业的输出。 更多信息请参阅 needs 上下文

作为表达式的一部分,您可以使用以下两种语法之一访问上下文信息。

  • 索引语法:github['sha']
  • 属性解除参考语法:github.sha

要使用属性解除参考语法,属性名称必须:

  • a-Z_ 开头。
  • 后跟 a-Z 0-9 -_

确定何时使用上下文

GitHub Actions 包含一个称为上下文的变量集和一个称为默认环境变量的类似变量集。 这些变量预期用于工作流程中的不同点:

  • 默认环境变量:这些变量仅存在于执行作业的运行器上。 更多信息请参阅“默认环境变量”。
  • 上下文:您可以在工作流程的任何时候使用大多数上下文,包括当默认环境变量不可用时。 例如,您可以使用带表达式的上下文执行初始处理,然后将作业路由到运行器以供执行;这允许您使用带有条件 if 关键字的上下文来确定步骤是否应运行。 作业运行后,您还可以从执行作业的运行器(如 runner.os)检索上下文变量。 有关您可以在工作流程中使用各种上下文的详细信息,请参阅“上下文可用性”。

下面的示例演示了这些不同类型的环境变量如何在一个作业中一起使用:

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

在此示例中,if 语句检查 github.ref 上下文以确定当前分支名称;如果名称是 refs/heads/main,则执行后续步骤。 if 检查由 GitHub Actions 处理,作业仅在结果为 true 时才发送到运行器。 作业发送到运行器后, 该步骤将执行并引用运行器的 $GITHUB_REF 环境变量。

github 上下文

github 上下文包含有关工作流程运行以及触发运行的事件相关信息。 您可以读取环境变量中的大多数 github 上下文数据。 有关环境变量的更多信息,请参阅“使用环境变量”。

警告:在使用整个 github 上下文时,请注意其中包括诸如 github.token 等敏感信息。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。

警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。

属性名称类型描述
github对象工作流程中任何作业或步骤期间可用的顶层上下文。
github.action字符串正在运行的操作的名称。 GitHub removes special characters or uses the name __run when the current step runs a script. If you use the same action more than once in the same job, the name will include a suffix with the sequence number with underscore before it. For example, the first script you run will have the name __run, and the second script will be named __run_2. 同样,actions/checkout 第二次调用时将变成 actionscheckout2
github.action_path字符串您的操作所在的路径。 您可以使用此路径轻松访问与操作位于同一仓库中的文件。 此属性仅在复合操作中才受支持。
github.actor字符串发起工作流程运行的用户的登录名。
github.base_ref字符串工作流程运行中拉取请求的 base_ref 或目标分支。 此属性仅在触发工作流程运行的事件为 pull_requestpull_request_target 时才可用。
github.event对象完整事件 web 挂钩有效负载。 更多信息请参阅“触发工作流程的事件”。 您可以使用上下文访问事件的个别属性。
github.event_name字符串触发工作流程运行的事件的名称。
github.event_path字符串运行器上完整事件 web 挂钩有效负载的路径。
github.head_ref字符串工作流程运行中拉取请求的 head_ref 或来源分支。 此属性仅在触发工作流程运行的事件为 pull_requestpull_request_target 时才可用。
github.job字符串当前作业的 job_id
github.ref字符串触发工作流程的分支或标记参考。 对于分支,格式为 refs/heads/<branch_name>,对于标记是 refs/tags/<tag_name>
github.repository字符串所有者和仓库名称。 例如 Codertocat/Hello-World
github.repository_owner字符串仓库所有者的名称。 例如 Codertocat
github.run_id字符串仓库中每个运行的唯一编号。 如果您重新执行工作流程运行,此编号不变。
github.run_number字符串仓库中特定工作流程每个运行的唯一编号。 此编号从 1(对应于工作流程的第一个运行)开始,然后随着每个新的运行而递增。 如果您重新执行工作流程运行,此编号不变。
github.run_attempt字符串A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run.
github.server_url字符串Returns the URL of the GitHub server. 例如:https://github.com
github.sha字符串触发工作流程的提交 SHA。
github.token字符串代表仓库上安装的 GitHub 应用程序进行身份验证的令牌。 这在功能上等同于 GITHUB_TOKEN 密码。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。
github.workflow字符串工作流程的名称。 如果工作流程文件未指定 name,此属性的值将是仓库中工作流程文件的完整路径。
github.workspace字符串使用 checkout 操作时步骤的默认工作目录和仓库的默认位置。

env 上下文

env 上下文包含已在工作流程、作业或步骤中设置的环境变量。 有关在工作流程中设置环境变量的更多信息,请参阅“GitHub Actions 的工作流程语法”。

env 上下文语法允许您在工作流程文件中使用环境变量的值。 您可以在步骤的任何键值中使用 env 上下文,但 iduses 键除外。 有关步骤语法的更多信息,请参阅“GitHub Actions 的工作流程语法”。

如果您想要在运行器中使用环境变量的值,请使用运行器操作系统的正常方法来读取环境变量。

属性名称类型描述
env对象此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。
env.<env_name>字符串特定环境变量的值。

job 上下文

job 上下文包含当前正在运行的作业相关信息。

属性名称类型描述
job对象此上下文针对工作流程运行中的每项作业而改变。 您可以从作业中的任何步骤访问此上下文。
job.container对象作业的容器相关信息。 有关容器的更多信息,请参阅“GitHub Actions 的工作流程语法”。
job.container.id字符串容器的 id。
job.container.network字符串容器网络的 id。 运行程序创建作业中所有容器使用的网络。
job.services对象为作业创建的服务容器。 有关服务容器的更多信息,请参阅“GitHub Actions 的工作流程语法”。
job.services.<service id>.id字符串服务容器的 id。
job.services.<service id>.network字符串服务容器网络的 id。 运行程序创建作业中所有容器使用的网络。
job.services.<service id>.ports对象服务容器显露的端口。
job.status字符串作业的当前状态。 可能的值包括 successfailurecancelled

steps 上下文

steps 上下文包含当前作业中已经运行的步骤相关信息。

属性名称类型描述
steps对象此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。
steps.<step id>.outputs对象为步骤定义的输出集。 更多信息请参阅“GitHub Actions 的元数据语法”。
steps.<step id>.conclusion字符串continue-on-error 应用之后完成的步骤的结果。 可能的值包括 successfailurecancelledskipped。 当 continue-on-error 步骤失败时,outcomefailure,但最终的 conclusionsuccess
steps.<step id>.outcome字符串continue-on-error 应用之前完成的步骤的结果。 可能的值包括 successfailurecancelledskipped。 当 continue-on-error 步骤失败时,outcomefailure,但最终的 conclusionsuccess
steps.<step id>.outputs.<output name>字符串特定输出的值。

runner 上下文

runner 上下文包含正在执行当前作业的运行器相关信息。

属性名称类型描述
runner.name字符串The name of the runner executing the job.
runner.os字符串执行作业的运行器的操作系统。 可能的值为 LinuxWindowsmacOS
runner.temp字符串运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。
runner.tool_cache字符串包含 GitHub 托管运行器预安装工具的目录路径。 更多信息请参阅“GitHub 托管运行器的规范”。

needs 上下文

needs 上下文包含定义为当前作业依赖项的所有作业的输出。 有关定义作业依赖项的更多信息,请参阅“GitHub Actions 的工作流程语法”。

属性名称类型描述
needs.<job id>对象当前作业依赖的单个作业。
needs.<job id>.outputs对象当前作业依赖的作业的输出集。
needs.<job id>.outputs.<output name>字符串当前作业依赖的作业的特定输出值。
needs.<job id>.result字符串当前作业依赖的作业的结果。 可能的值包括 successfailurecancelledskipped

打印上下文信息到日志文件的示例

要检查每个上下文中可访问的信息,您可以使用此工作流程文件示例。

警告:在使用整个 github 上下文时,请注意其中包括诸如 github.token 等敏感信息。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJSON(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJSON(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJSON(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJSON(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJSON(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJSON(matrix) }}
        run: echo "$MATRIX_CONTEXT"

上下文可用性

在整个工作流程运行过程中,提供不同的上下文。 例如,secrets 上下文只能用于作业中的某些地方。

此外,某些功能只能在某些地方使用。 例如, hashFiles 函数无法随处可用。

下表列出了工作流程中每一个上下文和特殊函数可以使用的地方。 除非下面列出,否则可以在任何地方使用函数。

路径上下文特殊函数
concurrencygithub
envgithub, secrets
jobs.<job_id>.concurrencygithub, needs, strategy, matrix
jobs.<job_id>.containergithub, needs, strategy, matrix
jobs.<job_id>.container.credentialsgithub, needs, strategy, matrix, env, secrets
jobs.<job_id>.container.env.<env_id>github, needs, strategy, matrix, job, runner, env, secrets
jobs.<job_id>.continue-on-errorgithub, needs, strategy, matrix
jobs.<job_id>.defaults.rungithub, needs, strategy, matrix, env
jobs.<job_id>.envgithub, needs, strategy, matrix, secrets
jobs.<job_id>.environmentgithub, needs, strategy, matrix
jobs.<job_id>.environment.urlgithub, needs, strategy, matrix, job, runner, env, steps
jobs.<job_id>.ifgithub, needsalways, cancelled, success, failure
jobs.<job_id>.namegithub, needs, strategy, matrix
jobs.<job_id>.outputs.<output_id>github, needs, strategy, matrix, job, runner, env, secrets, steps
jobs.<job_id>.runs-ongithub, needs, strategy, matrix
jobs.<job_id>.servicesgithub, needs, strategy, matrix
jobs.<job_id>.services.<service_id>.credentialsgithub, needs, strategy, matrix, env, secrets
jobs.<job_id>.services.<service_id>.env.<env_id>github, needs, strategy, matrix, job, runner, env, secrets
jobs.<job_id>.steps.continue-on-errorgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.envgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.ifgithub, needs, strategy, matrix, job, runner, env, stepsalways, cancelled, success, failure, hashFiles
jobs.<job_id>.steps.namegithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.rungithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.timeout-minutesgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.withgithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.steps.working-directorygithub, needs, strategy, matrix, job, runner, env, secrets, stepshashFiles
jobs.<job_id>.strategygithub, needs
jobs.<job_id>.timeout-minutesgithub, needs, strategy, matrix

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。