Skip to main content

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

Contexts

You can access context information in workflows and actions.

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

About contexts

Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Each context is an object that contains properties, which can be strings or other objects.

在不同的工作流运行条件下,上下文、对象和属性大不相同。 For example, the matrix context is only populated for jobs in a matrix.

You can access contexts using 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 running job. For more information, see job context.
stepsobjectInformation about the steps that have been run in the current job. For more information, see steps context.
runnerobjectInformation about the runner that is running the current job. For more information, see runner context.
secretsobjectContains the names and values of secrets that are available to a workflow run. For more information, see secrets context.
strategyobjectInformation about the matrix execution strategy for the current job. For more information, see strategy context.
matrixobjectContains the matrix properties defined in the workflow that apply to the current job. For more information, see matrix context.
needsobjectContains 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 can 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 letter or _ and contain only alphanumeric characters, -, or _.

If you attempt to dereference a non-existent property, it will evaluate to an empty string.

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 环境变量。

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

Example: printing context information to the log

You can print the contents of contexts to the log for debugging. The toJSON function is required to pretty-print JSON objects to the log.

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

YAML
name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        id: github_context_step
        run: echo '${{ toJSON(github) }}'
      - name: Dump job context
        run: echo '${{ toJSON(job) }}'
      - name: Dump steps context
        run: echo '${{ toJSON(steps) }}'
      - name: Dump runner context
        run: echo '${{ toJSON(runner) }}'
      - name: Dump strategy context
        run: echo '${{ toJSON(strategy) }}'
      - name: Dump matrix context
        run: echo '${{ toJSON(matrix) }}'

github context

The github context contains information about the workflow run and the event that triggered the run. You can also 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. This object contains all the properties listed below.
github.actionstringThe name of the action currently running, or the id of a step. GitHub removes special characters, and uses the name __run when the current step runs a script without an id. 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 an action is located. This property is only supported in composite actions. You can use this path to access files located in the same repository as the action.
github.action_refstringFor a step executing an action, this is the ref of the action being executed. For example, v2.
github.action_repositorystringFor a step executing an action, this is the owner and repository name of the action. For example, actions/checkout.
github.action_statusstringFor a composite action, the current result of the composite action.
github.actorstringThe username of the user that initiated the workflow run.
github.api_urlstringThe URL of the GitHub REST API.
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.envstringPath on the runner to the file that sets environment variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see "Workflow commands for GitHub Actions."
github.eventobjectThe full event webhook payload. You can access individual properties of the event using this context. This object is identical to the webhook payload of the event that triggered the workflow run, and is different for each event. The webhooks for each GitHub Actions event is linked in "Events that trigger workflows." For example, for a workflow run triggered by the push event, this object contains the contents of the push webhook payload.
github.event_namestringThe name of the event that triggered the workflow run.
github.event_pathstringThe path to the file on the runner that contains the full event webhook payload.
github.graphql_urlstringThe URL of the GitHub GraphQL API.
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.
Note: This context property is set by the Actions runner, and is only available within the execution steps of a job. Otherwise, the value of this property will be null.
github.refstring触发工作流程的分支或� �记参考。 对于 push 触发的工作流,这是推送的分支或� �记参考。 对于 pull_request 触发的工作流,这是拉取请求合并分支。 对于 release 触发的工作流,这是创建的发布� �记。 对于其他触发器,这是触发工作流运行的分支或� �记参考。 此变量仅在分支或� �记可用于事件类型时才会设置。 给定的参考� �式完整,这意味着对于分支,其� �式为 refs/heads/<branch_name>,对于拉取请求,其� �式为 refs/pull/<pr_number>/merge,对于� �签,其� �式为 refs/tags/<tag_name>。 例如,refs/heads/feature-branch-1
github.pathstringPath on the runner to the file that sets system PATH variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see "Workflow commands for GitHub Actions."
github.repositorystringThe owner and repository name. For example, Codertocat/Hello-World.
github.repository_ownerstringThe repository owner's name. For example, Codertocat.
github.repositoryUrlstringThe Git URL to the repository. For example, git://github.com/codertocat/hello-world.git.
github.retention_daysstringThe number of days that workflow run logs and artifacts are kept.
github.run_idstring存储库中每个工作流运行的唯一编号。 如果您重新执行工作流程运行,此编号不变。
github.run_numberstring仓库中特定工作流程每个运行的唯一编号。 工作流首次运行时,此编号从 1 开始,并随着每次新的运行而递增。 如果您重新执行工作流程运行,此编号不变。
github.server_urlstringThe URL of the GitHub server. For example: https://github.com.
github.shastring触发工作流的提交 SHA。 此提交 SHA 的值取决于触发工作流程的事件。 有关详细信息,请参阅“触发工作流的事件”。 例如,ffac537e6cbbf934b08745a378932722df287a53
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 "Automatic token authentication."
Note: This context property is set by the Actions runner, and is only available within the execution steps of a job. Otherwise, the value of this property will be null.
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 on the runner for steps, and the default location of your repository when using the checkout action.

Example contents of the github context

The following example context is from a workflow run triggered by the push event. The event object in this example has been truncated because it is identical to the contents of the push webhook payload.

注意:此上下文只是一个示例。 上下文的内容取决于正在运行的工作流。 在不同的工作流运行条件下,上下文、对象和属性大不相同。

{
  "token": "***",
  "job": "dump_contexts_to_log",
  "ref": "refs/heads/my_branch",
  "sha": "c27d339ee6075c1f744c5d4b200f7901aad2c369",
  "repository": "octocat/hello-world",
  "repository_owner": "octocat",
  "repositoryUrl": "git://github.com/octocat/hello-world.git",
  "run_id": "1536140711",
  "run_number": "314",
  "retention_days": "90",
  "run_attempt": "1",
  "actor": "octocat",
  "workflow": "Context testing",
  "head_ref": "",
  "base_ref": "",
  "event_name": "push",
  "event": {
    ...
  },
  "server_url": "https://github.com",
  "api_url": "https://api.github.com",
  "graphql_url": "https://api.github.com/graphql",
  "ref_name": "my_branch",
  "ref_protected": false,
  "ref_type": "branch",
  "secret_source": "Actions",
  "workspace": "/home/runner/work/hello-world/hello-world",
  "action": "github_step",
  "event_path": "/home/runner/work/_temp/_github_workflow/event.json",
  "action_repository": "",
  "action_ref": "",
  "path": "/home/runner/work/_temp/_runner_file_commands/add_path_b037e7b5-1c88-48e2-bf78-eaaab5e02602",
  "env": "/home/runner/work/_temp/_runner_file_commands/set_env_b037e7b5-1c88-48e2-bf78-eaaab5e02602"
}

Example usage of the github context

This example workflow uses the github.event_name context to run a job only if the workflow run was triggered by the pull_request event.

YAML
name: Run CI
on: [push, pull_request]

jobs:
  normal_ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run normal CI
        run: ./run-tests

  pull_request_ci:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - uses: actions/checkout@v2
      - name: Run PR CI
        run: ./run-additional-pr-ci

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. This object contains the properties listed below.
env.<env_name>stringThe value of a specific environment variable.

Example contents of the env context

The contents of the env context is a mapping of environment variable names to their values. The context's contents can change depending on where it is used in the workflow run.

{
  "first_name": "Mona",
  "super_duper_var": "totally_awesome"
}

Example usage of the env context

This example workflow shows how the env context can be configured at the workflow, job, and step levels, as well as using the context in steps.

当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的环境变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

YAML
name: Hi Mascot
on: push
env:
  mascot: Mona
  super_duper_var: totally_awesome

jobs:
  windows_job:
    runs-on: windows-latest
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Mona
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Octocat
        env:
          mascot: Octocat
  linux_job:
    runs-on: ubuntu-latest
    env:
      mascot: Tux
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Tux

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. This object contains all the properties listed below.
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.

Example contents of the job context

This example job context uses a PostgreSQL service container with mapped ports. If there are no containers or service containers used in a job, the job context only contains the status property.

{
  "status": "success",
  "container": {
    "network": "github_network_53269bd575974817b43f4733536b200c"
  },
  "services": {
    "postgres": {
      "id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105",
      "ports": {
        "5432": "49153"
      },
      "network": "github_network_53269bd575974817b43f4733536b200c"
    }
  }
}

Example usage of the job context

This example workflow configures a PostgreSQL service container, and automatically maps port 5432 in the service container to a randomly chosen available port on the host. The job context is used to access the number of the port that was assigned on the host.

YAML
name: PostgreSQL Service Example
on: push
jobs:
  postgres-job:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          # Maps TCP port 5432 in the service container to a randomly chosen available port on the host.
          - 5432

    steps:
      - uses: actions/checkout@v2
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: ./run-tests

steps context

The steps context contains information about the steps in the current job that have an id specified and 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. This object contains all the properties listed below.
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.

Example contents of the steps context

This example steps context shows two previous steps that had an id specified. The first step had the id named checkout, the second generate_number. The generate_number step had an output named random_number.

{
  "checkout": {
    "outputs": {},
    "outcome": "success",
    "conclusion": "success"
  },
  "generate_number": {
    "outputs": {
      "random_number": "1"
    },
    "outcome": "success",
    "conclusion": "success"
  }
}

Example usage of the steps context

This example workflow generates a random number as an output in one step, and a later step uses the steps context to read the value of that output.

YAML
name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - id: checkout
        uses: actions/checkout@v2
      - name: Generate 0 or 1
        id: generate_number
        run:  echo "::set-output name=random_number::$(($RANDOM % 2))"
      - name: Pass or fail
        run: |
          if [[ ${{ steps.generate_number.outputs.random_number }} == 0 ]]; then exit 0; else exit 1; fi

runner context

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

Property nameTypeDescription
runnerobjectThis context changes for each job in a workflow run. This object contains all the properties listed below.
runner.namestring执行作业的运行器的名称。
runner.osstring执行作业的运行器的操作系统。 可能的值为 LinuxWindowsmacOS
runner.tempstring运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限� 除这些文件,则不会被� 除。
runner.tool_cachestring包含 GitHub 托管运行器预安装工具的目录路径。 有关详细信息,请参阅“有关 GitHub 托管的运行器”。
runner.debugstring仅当启用调试日志记录并且始终具有值 1 时,才会进行此设置。 它可以用作指示器,以便在自己的作业步骤中启用更多调试或详细日志记录。

Example contents of the runner context

The following example context is from a Linux GitHub-hosted runner.

{
  "os": "Linux",
  "arch": "X64",
  "name": "GitHub Actions 2",
  "tool_cache": "/opt/hostedtoolcache",
  "temp": "/home/runner/work/_temp"
}

Example usage of the runner context

This example workflow uses the runner context to set the path to the temporary directory to write logs, and if the workflow fails, it uploads those logs as artifact.

YAML
name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build with logs
        run: |
          mkdir ${{ runner.temp }}/build_logs
          ./build.sh --log-path ${{ runner.temp }}/build_logs
      - name: Upload logs on fail
        if: ${{ failure() }}
        uses: actions/upload-artifact@v2
        with:
          name: Build failure logs
          path: ${{ runner.temp }}/build_logs

secrets context

The secrets context contains the names and values of secrets that are available to a workflow run. The secrets context is not available for composite actions. For more information about secrets, see "Encrypted secrets."

GITHUB_TOKEN is a secret that is automatically created for every workflow run, and is always included in the secrets context. For more information, see "Automatic token authentication."

警告:GitHub 自动将密� �编写到日志,但应避免有意将密� �打印到日志。

Property nameTypeDescription
secretsobjectThis context is the same for each job in a workflow run. You can access this context from any step in a job. This object contains all the properties listed below.
secrets.GITHUB_TOKENstringAutomatically created token for each workflow run. For more information, see "Automatic token authentication."
secrets.<secret_name>stringThe value of a specific secret.

Example contents of the secrets context

The following example contents of the secrets context shows the automatic GITHUB_TOKEN, as well as two other secrets available to the workflow run.

{
  "github_token": "***",
  "NPM_TOKEN": "***",
  "SUPERSECRET": "***"
}

Example usage of the secrets context

此示例工作流程使用 labeler 操作,该操作需要 GITHUB_TOKEN 作为 repo-token 输入参数的值:

YAML
name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v3
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

strategy context

For workflows with a matrix, the strategy context contains information about the matrix execution strategy for the current job.

Property nameTypeDescription
strategyobjectThis context changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below.
strategy.fail-fastbooleanWhen true, all in-progress jobs are canceled if any job in a matrix fails. For more information, see "Workflow syntax for GitHub Actions."
strategy.job-indexnumberThe index of the current job in the matrix. Note: This number is a zero-based number. The first job's index in the matrix is 0.
strategy.job-totalnumberThe total number of jobs in the matrix. Note: This number is not a zero-based number. For example, for a matrix with four jobs, the value of job-total is 4.
strategy.max-parallelnumberThe maximum number of jobs that can run simultaneously when using a matrix job strategy. For more information, see "Workflow syntax for GitHub Actions."

Example contents of the strategy context

The following example contents of the strategy context is from a matrix with four jobs, and is taken from the final job. Note the difference between the zero-based job-index number, and job-total which is not zero-based.

{
  "fail-fast": true,
  "job-index": 3,
  "job-total": 4,
  "max-parallel": 4
}

Example usage of the strategy context

This example workflow uses the strategy.job-index property to set a unique name for a log file for each job in a matrix.

YAML
name: Test matrix
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [1, 2]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v2
      - run: npm test > test-job-${{ strategy.job-index }}.txt
      - name: Upload logs
        uses: actions/upload-artifact@v2
        with:
          name: Build log for job ${{ strategy.job-index }}
          path: test-job-${{ strategy.job-index }}.txt

matrix context

For workflows with a matrix, the matrix context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a matrix with the os and node keys, the matrix context object includes the os and node properties with the values that are being used for the current job.

There are no standard properties in the matrix context, only those which are defined in the workflow file.

Property nameTypeDescription
matrixobjectThis context is only available for jobs in a matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below.
matrix.<property_name>stringThe value of a matrix property.

Example contents of the matrix context

The following example contents of the matrix context is from a job in a matrix that has the os and node matrix properties defined in the workflow. The job is executing the matrix combination of an ubuntu-latest OS and Node.js version 16.

{
  "os": "ubuntu-latest",
  "node": 16
}

Example usage of the matrix context

This example workflow creates a matrix with os and node keys. It uses the matrix.os property to set the runner type for each job, and uses the matrix.node property to set the Node.js version for each job.

YAML
name: Test matrix
on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

needs context

The needs context contains outputs from all jobs that are defined as a direct dependency of the current job. Note that this doesn't include implicitly dependent jobs (for example, dependent jobs of a dependent job). For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."

Property nameTypeDescription
needsobjectThis context is only populated for workflow runs that have dependent jobs, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below.
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 contents of the needs context

The following example contents of the needs context shows information for two jobs that the current job depends on.

{
  "build": {
    "result": "success",
    "outputs": {
      "build_id": "ABC123"
    }
  },
  "deploy": {
    "result": "failure",
    "outputs": {}
  }
}

Example usage of the needs context

This example workflow has three jobs: a build job that does a build, a deploy job that requires the build job, and a debug job that requires both the build and deploy jobs and runs only if there is a failure in the workflow. The deploy job also uses the needs context to access an output from the build job.

YAML
name: Build and deploy
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build_id: ${{ steps.build_step.outputs.build_id }}
    steps:
      - uses: actions/checkout@v2
      - name: Build
        id: build_step
        run: |
          ./build
          echo "::set-output name=build_id::$BUILD_ID"
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: ./deploy --build ${{ needs.build.outputs.build_id }}
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - uses: actions/checkout@v2
      - run: ./debug