Contexts

You can access context information in workflows and actions.

注意: GitHub Actions 目前正在测试用于 GitHub AE 。

About contexts

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

Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Contexts use the expression syntax. For more information, see "Expressions."

${{ <context> }}

Context nameTypeDescription
githubobjectInformation about the workflow run. For more information, see github context.
envobjectContains environment variables set in a workflow, job, or step. For more information, see env context.
jobobjectInformation about the currently executing job. For more information, see job context.
stepsobjectInformation about the steps that have been run in this job. For more information, see steps context.
runnerobjectInformation about the runner that is running the current job. For more information, see runner context.
secretsobjectEnables access to secrets. For more information about secrets, see "Creating and using encrypted secrets."
strategyobjectEnables access to the configured strategy parameters and information about the current job. Strategy parameters include fail-fast, job-index, job-total, and max-parallel.
matrixobjectEnables access to the matrix parameters you configured for the current job. For example, if you configure a matrix build with the os and node versions, the matrix context object includes the os and node versions of the current job.
needsobjectEnables access to the outputs of all jobs that are defined as a dependency of the current job. For more information, see needs context.

As part of an expression, you may access context information using one of two syntaxes.

  • Index syntax: github['sha']
  • Property dereference syntax: github.sha

In order to use property dereference syntax, the property name must:

  • start with a-Z or _.
  • be followed by a-Z 0-9 - or _.

Determining when to use contexts

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 context

The github context contains information about the workflow run and the event that triggered the run. You can read most of the github context data in environment variables. For more information about environment variables, see "Using environment variables."

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

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

Property nameTypeDescription
githubobjectThe top-level context available during any job or step in a workflow.
github.actionstringThe name of the action currently running. 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. Similarly, the second invocation of actions/checkout will be actionscheckout2.
github.action_pathstringThe path where your action is located. You can use this path to easily access files located in the same repository as your action. This attribute is only supported in composite actions.
github.actorstringThe login of the user that initiated the workflow run.
github.base_refstringThe base_ref or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either pull_request or pull_request_target.
github.eventobjectThe full event webhook payload. For more information, see "Events that trigger workflows." You can access individual properties of the event using this context.
github.event_namestringThe name of the event that triggered the workflow run.
github.event_pathstringThe path to the full event webhook payload on the runner.
github.head_refstringThe head_ref or source branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either pull_request or pull_request_target.
github.jobstringThe job_id of the current job.
github.refstringThe branch or tag ref that triggered the workflow run. For branches this is the format refs/heads/<branch_name>, and for tags it is refs/tags/<tag_name>.
github.repositorystringThe owner and repository name. For example, Codertocat/Hello-World.
github.repository_ownerstringThe repository owner's name. For example, Codertocat.
github.run_idstring仓库中每个运行的唯一编号。 如果您重新执行工作流程运行,此编号不变。
github.run_numberstring仓库中特定工作流程每个运行的唯一编号。 此编号从 1(对应于工作流程的第一个运行)开始,然后随着每个新的运行而递增。 如果您重新执行工作流程运行,此编号不变。
github.run_attemptstringA 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_urlstringReturns the URL of the GitHub server. For example: https://github.com.
github.shastringThe commit SHA that triggered the workflow run.
github.tokenstringA token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the GITHUB_TOKEN secret. For more information, see "Authenticating with the GITHUB_TOKEN."
github.workflowstringThe name of the workflow. If the workflow file doesn't specify a name, the value of this property is the full path of the workflow file in the repository.
github.workspacestringThe default working directory for steps and the default location of your repository when using the checkout action.

env context

The env context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "Workflow syntax for GitHub Actions."

The env context syntax allows you to use the value of an environment variable in your workflow file. You can use the env context in the value of any key in a step except for the id and uses keys. For more information on the step syntax, see "Workflow syntax for GitHub Actions."

If you want to use the value of an environment variable inside a runner, use the runner operating system's normal method for reading environment variables.

Property nameTypeDescription
envobjectThis context changes for each step in a job. You can access this context from any step in a job.
env.<env_name>stringThe value of a specific environment variable.

job context

The job context contains information about the currently running job.

Property nameTypeDescription
jobobjectThis context changes for each job in a workflow run. You can access this context from any step in a job.
job.containerobjectInformation about the job's container. For more information about containers, see "Workflow syntax for GitHub Actions."
job.container.idstringThe id of the container.
job.container.networkstringThe id of the container network. The runner creates the network used by all containers in a job.
job.servicesobjectThe service containers created for a job. For more information about service containers, see "Workflow syntax for GitHub Actions."
job.services.<service id>.idstringThe id of the service container.
job.services.<service id>.networkstringThe id of the service container network. The runner creates the network used by all containers in a job.
job.services.<service id>.portsobjectThe exposed ports of the service container.
job.statusstringThe current status of the job. Possible values are success, failure, or cancelled.

steps context

The steps context contains information about the steps in the current job that have already run.

Property nameTypeDescription
stepsobjectThis context changes for each step in a job. You can access this context from any step in a job.
steps.<step id>.outputsobjectThe set of outputs defined for the step. For more information, see "Metadata syntax for GitHub Actions."
steps.<step id>.conclusionstringThe result of a completed step after continue-on-error is applied. Possible values are success, failure, cancelled, or skipped. When a continue-on-error step fails, the outcome is failure, but the final conclusion is success.
steps.<step id>.outcomestringThe result of a completed step before continue-on-error is applied. Possible values are success, failure, cancelled, or skipped. When a continue-on-error step fails, the outcome is failure, but the final conclusion is success.
steps.<step id>.outputs.<output name>stringThe value of a specific output.

runner context

The runner context contains information about the runner that is executing the current job.

Property nameTypeDescription
runner.namestringThe name of the runner executing the job.
runner.osstring执行作业的运行器的操作系统。 可能的值为 LinuxWindowsmacOS
runner.tempstring运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。
runner.tool_cachestringFor instructions on how to make sure your AE 托管的运行器 has the required software installed, see "Creating custom images."

needs context

The needs context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."

Property nameTypeDescription
needs.<job id>objectA single job that the current job depends on.
needs.<job id>.outputsobjectThe set of outputs of a job that the current job depends on.
needs.<job id>.outputs.<output name>stringThe value of a specific output for a job that the current job depends on.
needs.<job id>.resultstringThe result of a job that the current job depends on. Possible values are success, failure, cancelled, or skipped.

Example printing context information to the log file

To inspect the information that is accessible in each context, you can use this workflow file example.

警告:在使用整个 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"

Context availability

Different contexts are available throughout a workflow run. For example, the secrets context may only be used at certain places within a job.

In addition, some functions may only be used in certain places. For example, the hashFiles function is not available everywhere.

The following table indicates where each context and special function can be used within a workflow. Unless listed below, a function can be used anywhere.

PathContextSpecial functions
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 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。