GitHub Actions のコンテキストおよび式の構文

ワークフローおよびアクションにおいて、コンテキスト情報へのアクセスおよび式の評価が可能です。

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 For more information, see "GitHub's products."

コンテキストと式について

プログラムでワークフローファイルの変数を設定したり、コンテキストにアクセスするために、式を利用できます。式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。

式は、ステップを実行すべきか判断するための if 条件キーワードをワークフローファイル内に記述して使用するのが一般的です。 if条件がtrueになれば、ステップは実行されます。

ある式を、文字列型として扱うのではなく式として評価するためには、特定の構文を使って GitHub に指示する必要があります。

${{ <expression> }}

if 条件の中で式を使用する際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 if条件の詳細については、「GitHub Actionsのためのワークフローの構文」を参照してください。

`if` 条件内の式の例

steps:
  - uses: actions/hello-world-javascript-action@v1.1
    if: ${{ <expression> }}

環境変数の設定例

env:
  my_env_var: ${{ <expression> }}

コンテキスト

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

${{ <context> }}

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

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

インデックス構文: github['sha']
プロパティ参照外しの構文: github.sha

プロパティ参照外しの構文を使用するには、プロパティ名に次の条件が必要です。

a-Z または _ で始まる。
a-Z 、0-9、 -、または_が続く。

Determining when to use contexts

GitHub Actions includes a collection of variables called contexts and a similar collection of variables called default environment variables. These variables are intended for use at different points in the workflow:

Default environment variables: These variables exist only on the runner that is executing your job. 詳しい情報については、「デフォルトの環境変数」を参照してください。
Contexts: You can use most contexts at any point in your workflow, including when default environment variables would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional if keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such as runner.os. 詳細については、「コンテキスト」を参照してください。

The following example demonstrates how these different types of environment variables can be used together in a job:

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"

In this example, the if statement checks the github.ref context to determine the current branch name; if the name is refs/heads/main, then the subsequent steps are executed. The if check is processed by GitHub Actions, and the job is only sent to the runner if the result is true. Once the job is sent to the runner, the step is executed and refers to the $GITHUB_REF environment variable from the runner.

`github` コンテキスト

github コンテキストは、ワークフローの実行および、その実行をトリガーしたイベントの情報を含みます。ほとんどの github コンテキストデータは、環境変数で読み取ることができます。環境変数に関する詳しい情報については、「環境変数の利用」を参照してください。

警告: githubコンテキスト全体を使う場合には、github.tokenのようなセンシティブな情報が含まれていることを忘れないようにしてください。 GitHubは、シークレットがコンソールに出力される際にはマスクしますが、コンテキストをエクスポートしたりプリントしたりするときには注意が必要です。

プロパティ名	種類	説明
`github`	`オブジェクト`	ワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。
`github.action`	`string`	現在実行中のアクションの名前。 GitHubは、現在のステップがステップを実行する際に、特殊なキャラクターを削除するか、`run`という名前を使います。同じジョブの中で同じアクションを複数回使う場合、名前には順番に番号が加えられます。たとえば、実行する最初のスクリプトの名前は`run1`で、2番目のスクリプトの名前は`run2`というようになります。同様に、`actions/checkout`の2回目の呼び出しは`actionscheckout2`となります。
`github.action_path`	`string`	アクションが置かれているパス。このパスを使用して、アクションと同じリポジトリにあるファイルに簡単にアクセスできます。この属性は、複合実行ステップアクションでのみサポートされています。
`github.actor`	`string`	ワークフローの実行を開始したユーザのログイン。
`github.base_ref`	`string`	ワークフローの実行における `base_ref` またはプルリクエストのターゲットブランチ。このプロパティは、ワークフローの実行をトリガーしたイベントが `pull_request` の場合のみ使用できます。
`github.event`	`オブジェクト`	webhook ペイロードの完全なイベント。詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。このコンテキストを使用して、イベントの個々のプロパティにアクセスできます。
`github.event_name`	`string`	ワークフローの実行をトリガーしたイベントの名前。
`github.event_path`	`string`	ランナー上の完全なイベントwebhookペイロードへのパス。
`github.head_ref`	`string`	ワークフローの実行における `head_ref` またはプルリクエストのソースブランチ。このプロパティは、ワークフローの実行をトリガーしたイベントが `pull_request` の場合のみ使用できます。
`github.job`	`string`	現在のジョブの`job_id`。
`github.ref`	`string`	ワークフローの実行をトリガーしたブランチまたはタグ ref。ブランチの場合、これは `refs/heads/<branch_name>` の形式で、タグの場合は `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.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の構文で、ワークフローファイル中の環境変数の値を利用できます。 You can use the env context in the value of any key in a step except for the id and uses keys. ステップの構文に関する詳しい情報については「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.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コンテキスト全体を使う場合には、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"

リテラル

式の一部として、boolean、null、number、またはstringのデータ型を使用できます。 boolean のリテラルは大文字と小文字を区別しないので、true も True も使用できます。

データ型	リテラル値
`boolean`	`true` または `false`
`null`	`null`
`number`	JSONでサポートされている任意の数値書式。
`string`	一重引用符で囲む必要があります。一重引用符そのものを使用するには、一重引用符でエスケープしてください。

サンプル

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99-e2 }}
  myString: ${{ 'Mona the Octocat' }}
  myEscapedString: ${{ 'It''s open source!' }}

演算子

演算子	説明
`( )`	論理グループ化
`[ ]`	インデックス
`.`	プロパティ参照外し
`!`	否定
`<`	小なり
`<=`	以下
`>`	大なり
`>=`	以上
`==`	等しい
`!=`	等しくない
`&&`	AND
`\|\|`	OR

GitHub は、等価性を緩やかに比較します。

型が一致しない場合、GitHub は型を強制的に数値とします。 GitHub は、以下の変換方法で、データ型を数字にキャストします。

種類	結果
ヌル	`0`
論理値	`true`は`1`を返します。 `false`は`0`を返します。
文字列型	正規のJSON数値型からパースされます。それ以外の場合は`NaN`です。注釈: 空の文字列は `0` を返します。
配列	`NaN`
オブジェクト	`NaN`

ある NaN を、別の NaN と比較すると、true は返ってきません。詳しい情報については、「NaN Mozilla ドキュメント」を参照してください。
GitHub は、文字列を比較する際に大文字と小文字を区別しません。
オブジェクトおよび配列は、同じインスタンスの場合にのみ等しいとみなされます。

関数

GitHub は、式で使用できる組み込み関数のセットを提供します。一部の関数は、比較を行なうために、値を文字列型にキャストします。 GitHub は、以下の変換方法で、データ型を文字列にキャストします。

種類	結果
ヌル	`''`
論理値	`'true'`または`'false'`
Number	10進数、大きい場合は指数
配列	配列は文字列型に変換されません
オブジェクト	オブジェクトは文字列型に変換されません

contains

contains( search, item )

searchがitem を含む場合、true を返します。 searchが配列の場合、itemが配列の要素であれば、この関数はtrueを返します。 searchが文字列の場合、itemがsearchの部分文字列であれば、この関数はtrueを返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。

配列の利用例

contains(github.event.issue.labels.*.name, 'bug')

文字列の使用例

contains('Hello world', 'llo') は、true を返します。

startsWith

startsWith( searchString, searchValue )

searchString が searchValue で始まる場合、true を返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。

サンプル

startsWith('Hello world', 'He') は、true を返します

endsWith

endsWith( searchString, searchValue )

searchString が searchValue で終わる場合、true を返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。

サンプル

endsWith('Hello world', 'ld') は、true を返します

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

string の値を、変数 replaceValueN で置換します。 string の変数は、{N} という構文で指定します。ここで N は整数です。少なくとも、replaceValue と string を 1 つ指定する必要があります。使用できる変数 (replaceValueN) の数に制限はありません。中括弧はダブルスペースでエスケープします。

サンプル

'Hello Mona the Octocat' を返します

format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')

括弧をエスケープするサンプル

'{Hello Mona the Octocat!}'を返します。

format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat')

join

join( array, optionalSeparator )

arrayの値は、配列もしくは文字列になります。 array内のすべての値が連結されて文字列になります。 optionalSeparatorを渡すと、連結された値の間にその値が挿入されます。渡していない場合は、デフォルトのセパレータの,が使われます。値を文字列にキャストします。

サンプル

join(github.event.issue.labels.*.name, ', ')は'bug, help wanted'といった結果を返します。

toJson

toJSON(value)

value を、書式を整えたJSON表現で返します。この関数を使って、コンテキスト内で提供された情報のデバッグができます。

サンプル

toJSON(job) は、{ "status": "Success" } を返す可能性があります。

fromJson

fromJSON(value)

valueに対するJSONオブジェクトを返します。この関数は、評価された式としてJSONオブジェクトを提供するために利用できます。

サンプル

以下のワークフローはJSONのマトリックスを1つのジョブに設定し、それを出力とfromJSONを使って次のジョブに渡します。

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
    - id: set-matrix
      run: echo "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{fromJson(needs.job1.outputs.matrix)}}
    steps:
    - run: build

hashFiles

hashFiles(path)

pathパターンにマッチするファイル群から単一のハッシュを返します。単一の path パターンまたはコンマで区切られた複数の path パターンを指定できます。 pathはGITHUB_WORKSPACEディレクトリに対する相対であり、含められるのはGITHUB_WORKSPACE内のファイルだけです。この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 SHA-256に関する詳しい情報については「SHA-2」を参照してください。

パターンマッチング文字を使ってファイル名をマッチさせることができます。パターンマッチングは、Windowsでは大文字小文字を区別しません。サポートされているパターンマッチング文字に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

単一のパターンの例

リポジトリ内の任意のpackage-lock.jsonファイルにマッチします。

hashFiles('**/package-lock.json')

複数のパターンの例

リポジトリ内の package-lock.json および Gemfile.lock ファイルのハッシュを作成します。

hashFiles('**/package-lock.json', '**/Gemfile.lock')

ジョブステータスのチェック関数

if 条件では、次のステータスチェック関数を式として使用できます。 if 条件ステータス関数が含まれていない場合、結果は自動的に success() になります。 if 条件に関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。

success

以前のステップで失敗もしくはキャンセルされたものがない場合にtrueを返します。

サンプル

steps:
  ...
  - name: The job has succeeded
    if: ${{ success() }}

always

常にtrueを返します。キャンセルされた場合であっても同じです。クリティカルなエラーによりタスクが実行されない場合は、ジョブやステップも実行されません。たとえば、ソースの取得に失敗した場合などがそれにあたります。

サンプル

if: ${{ always() }}

cancelled

ワークフローがキャンセルされた場合、true を返します。

サンプル

if: ${{ cancelled() }}

failure

ジョブの以前のステップのいずれかが失敗したならtrueを返します。

サンプル

steps:
  ...
  - name: The job has failed
    if: ${{ failure() }}

オブジェクトフィルタ

* 構文を使って、フィルタを適用し、コレクション内の一致するアイテムを選択できます。

たとえば、fruitsというオブジェクトの配列を考えます。

[
  { "name": "apple", "quantity": 1 },
  { "name": "orange", "quantity": 2 },
  { "name": "pear", "quantity": 1 }
]

fruits.*.nameというフィルタを指定すると、配列[ "apple", "orange", "pear" ]が返されます。

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.

GitHub Actions のコンテキストおよび式の構文

Did this doc help you?

Help us make these docs great!

Still need help?