コンテキスト

About contexts

コンテキストは、ワークフローの実行、ランナーの環境、ジョブ、ステップに関する情報にアクセスする方法です。 コンテキストは式の構文を使用します。 For more information, see "Expressions."

${{ <context> }}

コンテキスト名	種類	説明
github	オブジェクト	ワークフロー実行に関する情報。 詳しい情報については、「github コンテキスト」を参照してください。
env	オブジェクト	ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 詳しい情報については、env コンテキストを参照してください。
ジョブ	オブジェクト	現在実行中のジョブに関する情報。 詳しい情報については、「job コンテキスト」を参照してください。
steps	オブジェクト	このジョブで実行されているステップに関する情報。 詳しい情報については、「steps コンテキスト」を参照してください。
runner	オブジェクト	現在のジョブを実行しているランナーに関する情報。 詳しい情報についてはrunnerコンテキストを参照してください。
secrets	オブジェクト	シークレットへのアクセスを有効にします。 シークレットに関する詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。
strategy	オブジェクト	現在のジョブに関して設定されたstrategyパラメータおよび情報にアクセスできます。 strategyパラメータには、fail-fast、job-index、job-total、max-parallelがあります。
matrix	オブジェクト	現在のジョブに対して決定したmatrixパラメータにアクセスできます。 例えば、osおよびnode バージョンでマトリックスビルドを設定した場合、matrixコンテキストオブジェクトには現在のジョブのosおよびnodeバージョンが含まれます。
needs	オブジェクト	現在のジョブの依存関係として定義されたすべてのジョブの出力へのアクセスを可能にします。 詳しい情報についてはneedsコンテキストを参照してください。

式の一部として、次の 2 つの構文のうちいずれかを使用してコンテキストにアクセスすることができます。

• インデックス構文: 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	string	現在実行中のアクションの名前。 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の2回目の呼び出しはactionscheckout2となります。
github.action_path	string	アクションが置かれているパス。 このパスを使用して、アクションと同じリポジトリにあるファイルに簡単にアクセスできます。 This attribute is only supported in composite actions.
github.actor	string	ワークフローの実行を開始したユーザのログイン。
github.base_ref	string	ワークフローの実行における base_ref またはPull Requestのターゲットブランチ。 このプロパティは、ワークフローの実行をトリガーするイベントが pull_request または pull_request_target のいずれかである場合にのみ使用できます。
github.event	オブジェクト	webhook ペイロードの完全なイベント。 詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。 このコンテキストを使用して、イベントの個々のプロパティにアクセスできます。
github.event_name	string	ワークフローの実行をトリガーしたイベントの名前。
github.event_path	string	ランナー上の完全なイベントwebhookペイロードへのパス。
github.head_ref	string	ワークフローの実行における head_ref またはPull Requestのソースブランチ。 このプロパティは、ワークフローの実行をトリガーするイベントが pull_request または pull_request_target のいずれかである場合にのみ使用できます。
github.job	string	現在のジョブのjob_id。
github.ref	string	ワークフローの実行をトリガーしたブランチまたはタグ ref。 For branches this is the format refs/heads/<branch_name>, and for tags it is refs/tags/<tag_name>.
github.repository	string	所有者およびリポジトリの名前。 Codertocat/Hello-Worldなどです。
github.repository_owner	string	リポジトリのオーナーの名前。 たとえばCodertocat。
github.run_id	string	リポジトリ内でユニークな各実行に対する番号。 この番号は、ワークフローの実行をやり直しても変化しません、
github.run_number	string	リポジトリ内の特定のワークフローの各実行に対するユニークな番号。 この番号は、ワークフローの最初の実行時に1で始まり、新たな実行ごとにインクリメントされます。 この番号は、ワークフローの実行をやり直しても変化しません、
github.run_attempt	string	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	string	Returns the URL of the GitHub server. たとえば、https://github.com などです。
github.sha	string	ワークフローの実行をトリガーしたコミット SHA。
github.token	string	リポジトリにインストールされたGitHub Appの代わりに認証するためのトークン。 これは機能的にGITHUB_TOKENシークレットに等価です。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。
github.workflow	string	ワークフローの名前。 ワークフローファイルで name を指定していない場合、このプロパティの値は、リポジトリ内にあるワークフローファイルのフルパスになります。
github.workspace	string	checkoutアクションを使う際の、ステップにとってのデフォルトのワーキングディレクトリであり、リポジトリのデフォルトの場所です。

envコンテキスト

envコンテキストには、ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 ワークフローでの環境変数の設定に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

envの構文で、ワークフローファイル中の環境変数の値を利用できます。 id及びusesキーを除く、step中の任意のキーの値でenvコンテキストを利用できます。 ステップの構文に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

ランナー中で環境変数の値を使いたい場合は、ランナーのオペレーティングシステムで環境変数を読み取る通常の方法を使ってください。

プロパティ名	種類	説明
env	オブジェクト	このコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
env.<env_name>	string	特定の環境変数の値。

job コンテキスト

job コンテキストは、現在実行中のジョブに関する情報を含みます。

プロパティ名	種類	説明
ジョブ	オブジェクト	このコンテキストは、実行しているジョブごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
job.container	オブジェクト	ジョブのコンテナに関する情報。 コンテナに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。
job.container.id	string	コンテナの ID。
job.container.network	string	コンテナネットワークの ID。 runner は、コンテナ内のすべてのジョブに使用されるネットワークを作成します。
job.services	オブジェクト	ジョブのために作成されたサービスコンテナ。 サービスコンテナに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。
job.services.<service id>.id	string	サービスコンテナの ID。
job.services.<service id>.network	string	サービスコンテナネットワークの ID。 runner は、コンテナ内のすべてのジョブに使用されるネットワークを作成します。
job.services.<service id>.ports	オブジェクト	サービスコンテナの公開ポート。
job.status	string	ジョブの現在の状態。 success、failure、cancelled のいずれかの値をとります。

steps コンテキスト

steps コンテキストは、すでに実行中のジョブ内のステップに関する情報を含みます。

プロパティ名	種類	説明
steps	オブジェクト	このコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
steps.<step id>.outputs	オブジェクト	ステップに定義された出力のセット。 詳しい情報については、「GitHub Actions のメタデータ構文」を参照してください。
steps.<step id>.conclusion	string	continue-on-errorが適用された後に完了したステップの結果。 success、failure、cancelled、skippedのいずれかの値をとります。 continue-on-errorのステップが失敗すると、outcomeはfailureになりますが、最終的なconclusionはsuccessになります。
steps.<step id>.outcome	string	continue-on-errorが適用される前の完了したステップの結果。 success、failure、cancelled、skippedのいずれかの値をとります。 continue-on-errorのステップが失敗すると、outcomeはfailureになりますが、最終的なconclusionはsuccessになります。
steps.<step id>.outputs.<output name>	string	特定の出力の値。

runnerコンテキスト

runnerコンテキストには、現在のジョブを実行しているランナーに関する情報が含まれています。

プロパティ名	種類	説明
runner.name	string	The name of the runner executing the job.
runner.os	string	ジョブを実行しているランナーのオペレーティングシステム。 取り得る値はLinux、Windows、macOSのいずれか。
runner.temp	string	ランナー上の一時ディレクトリへのパス。 このディレクトリは、各ジョブの開始及び終了時点で空になります。 ランナーのユーザアカウントが削除する権限を持っていない場合、ファイルは削除されないことに注意してください。
runner.tool_cache	string	GitHubホストランナーにプレインストールされているツールを含むディレクトリへのパス。 詳しい情報については、「GitHub ホストランナーの仕様」を参照してください。

needsコンテキスト

needsコンテキストは、現在のジョブの依存関係として定義されたすべてのジョブからの出力を含みます。 ジョブの依存関係の定義に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

プロパティ名	種類	説明
needs.<job id>	オブジェクト	現在のジョブが依存している1つのジョブ。
needs.<job id>.outputs	オブジェクト	現在のジョブが依存しているジョブの出力の集合。
needs.<job id>.outputs.<output name>	string	現在のジョブが依存しているジョブの特定の出力の値。
needs.<job id>.result	string	現在のジョブが依存しているジョブの結果。 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"

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.

パス	コンテキスト	Special functions
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