上下文

About contexts

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

${{ <context> }}

上下文名称	类型	描述
github	对象	工作流程运行的相关信息。 更多信息请参阅 github 上下文。
env	对象	包含工作流程、作业或步骤中设置的环境变量。 更多信息请参阅 env 上下文。
job	对象	当前执行的作业相关信息。 更多信息请参阅 job 上下文。
steps	对象	此作业中已经运行的步骤的相关信息。 更多信息请参阅 steps 上下文。
runner	对象	运行当前作业的运行程序相关信息。 更多信息请参阅 runner 上下文。
secrets	对象	启用对密码的访问权限。 有关密码的更多信息，请参阅“创建和使用加密密码”。
strategy	对象	用于访问配置的策略参数及当前作业的相关信息。 策略参数包括 fail-fast、job-index、job-total 和 max-parallel。
matrix	对象	用于访问为当前作业配置的矩阵参数。 例如，如果使用 os 和 node 版本配置矩阵构建，matrix 上下文对象将包含当前作业的 os 和 node 版本。
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.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_request 或 pull_request_target 时才可用。
github.event	对象	完整事件 web 挂钩有效负载。 更多信息请参阅“触发工作流程的事件”。 您可以使用上下文访问事件的个别属性。
github.event_name	字符串	触发工作流程运行的事件的名称。
github.event_path	字符串	运行器上完整事件 web 挂钩有效负载的路径。
github.head_ref	字符串	工作流程运行中拉取请求的 head_ref 或来源分支。 此属性仅在触发工作流程运行的事件为 pull_request 或 pull_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 上下文，但 id 和 uses 键除外。 有关步骤语法的更多信息，请参阅“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	字符串	作业的当前状态。 可能的值包括 success、failure 或 cancelled。

steps 上下文

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

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

runner 上下文

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

属性名称	类型	描述
runner.name	字符串	The name of the runner executing the job.
runner.os	字符串	执行作业的运行器的操作系统。 可能的值为 Linux、Windows 或 macOS。
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	字符串	当前作业依赖的作业的结果。 可能的值包括 success、failure、cancelled 或 skipped。

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

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

.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 函数无法随处可用。

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

路径	上下文	特殊函数
concurrency	github
env	github, secrets
jobs.<job_id>.concurrency	github, needs, strategy, matrix
jobs.<job_id>.container	github, needs, strategy, matrix
jobs.<job_id>.container.credentials	github, 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-error	github, needs, strategy, matrix
jobs.<job_id>.defaults.run	github, needs, strategy, matrix, env
jobs.<job_id>.env	github, needs, strategy, matrix, secrets
jobs.<job_id>.environment	github, needs, strategy, matrix
jobs.<job_id>.environment.url	github, needs, strategy, matrix, job, runner, env, steps
jobs.<job_id>.if	github, needs	always, cancelled, success, failure
jobs.<job_id>.name	github, needs, strategy, matrix
jobs.<job_id>.outputs.<output_id>	github, needs, strategy, matrix, job, runner, env, secrets, steps
jobs.<job_id>.runs-on	github, needs, strategy, matrix
jobs.<job_id>.services	github, needs, strategy, matrix
jobs.<job_id>.services.<service_id>.credentials	github, 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-error	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.steps.env	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.steps.if	github, needs, strategy, matrix, job, runner, env, steps	always, cancelled, success, failure, hashFiles
jobs.<job_id>.steps.name	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.steps.run	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.steps.timeout-minutes	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.steps.with	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.steps.working-directory	github, needs, strategy, matrix, job, runner, env, secrets, steps	hashFiles
jobs.<job_id>.strategy	github, needs
jobs.<job_id>.timeout-minutes	github, needs, strategy, matrix