Contexts

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> }}

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.

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.

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."

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.

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.

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は最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。

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.

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.

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.

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.

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.

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.

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."

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

次のワークフローの例では、repo-token 入力パラメーターの値として GITHUB_TOKEN を必要とするラベラー アクションを使用します。

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.

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.

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.

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.

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."

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.

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