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

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

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。詳しい情報については「GitHubの製品」を参照してください。

ここには以下の内容があります:

コンテキストと式について
コンテキスト
リテラル
演算子
関数
ジョブステータスのチェック関数
オブジェクトフィルタ

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

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

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

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

${{ <expression> }}

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

`if` 条件内の式の例

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

環境変数の設定例

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

コンテキスト

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

${{ <context> }}

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

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

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

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

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

`github` コンテキスト

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

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

プロパティ名	種類	説明
`github`	`object`	ワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。
`github.event`	`object`	webhook ペイロードの完全なイベント。詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。
`github.event_path`	`string`	ランナー上の完全なイベントwebhookペイロードへのパス。
`github.workflow`	`string`	ワークフローの名前。ワークフローファイルで `name` を指定していない場合、このプロパティの値は、リポジトリ内にあるワークフローファイルのフルパスになります。
`github.job`	`string`	現在のジョブの`job_id`。
`github.run_id`	`string`	リポジトリ内でユニークな各実行に対する番号。この番号は、ワークフローの実行をやり直しても変化しません。
`github.run_number`	`string`	リポジトリ内の特定のワークフローの各実行に対するユニークな番号。この番号は、ワークフローの最初の実行時に1で始まり、新たな実行ごとにインクリメントされます。この番号は、ワークフローの実行をやり直しても変化しません、
`github.actor`	`string`	ワークフローの実行を開始したユーザのログイン。
`github.repository`	`string`	所有者およびリポジトリの名前。 `Codertocat/Hello-World`などです。
`github.repository_owner`	`string`	リポジトリのオーナーの名前。たとえば`Codertocat`。
`github.event_name`	`string`	ワークフローの実行をトリガーしたイベントの名前。
`github.sha`	`string`	ワークフローの実行をトリガーしたコミット SHA。
`github.ref`	`string`	ワークフローの実行をトリガーしたブランチまたはタグ ref。
`github.head_ref`	`string`	ワークフローの実行における `head_ref` またはプルリクエストのソースブランチ。このプロパティは、ワークフローの実行をトリガーしたイベントが `pull_request` の場合のみ使用できます。
`github.base_ref`	`string`	ワークフローの実行における `base_ref` またはプルリクエストのターゲットブランチ。このプロパティは、ワークフローの実行をトリガーしたイベントが `pull_request` の場合のみ使用できます。
`github.token`	`string`	リポジトリにインストールされたGitHub Appの代わりに認証するためのトークン。これは機能的に`GITHUB_TOKEN`シークレットに等価です。詳しい情報については「GITHUB_TOKENでの認証」を参照してください。
`github.workspace`	`string`	`checkout`アクションを使う際の、ステップにとってのデフォルトのワーキングディレクトリであり、リポジトリのデフォルトの場所です。
`github.action`	`string`	現在実行中のアクションの名前。 GitHubは、現在のステップがステップを実行する際に、特殊なキャラクターを削除するか、`run`という名前を使います。同じジョブの中で同じアクションを複数回使う場合、名前には順番に番号が加えられます。たとえば、実行する最初のスクリプトの名前は`run1`で、2番目のスクリプトの名前は`run2`というようになります。同様に、`actions/checkout`の2回目の呼び出しは`actionscheckout2`となります。

`env`コンテキスト

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

envの構文で、ワークフローファイル中の環境変数の値を利用できます。ランナー中で環境変数の値を使いたい場合は、ランナーのオペレーティングシステムで環境変数を読み取る通常の方法を使ってください。

envはwith及びnameキーの値の中で、あるいはステップのif条件の中でのみ使えます。ステップの構文に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

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

`job` コンテキスト

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

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

`steps` コンテキスト

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

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

`runner`コンテキスト

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

プロパティ名	種類	説明
`os`	`string`	ジョブを実行しているランナーのオペレーティングシステム。取り得る値は`Linux`、`Windows`、`macOS`のいずれか。
`temp`	`string`	ランナー用のテンポラリディレクトリのパス。このディレクトリは、セルフホストランナーの場合であっても、各ジョブの開始時点では空であることが保証されています。
`tool_cache`	`string`	GitHubホストランナーにプレインストールされているいくつかのツールを含むディレクトリのパス。詳しい情報については「GitHUbホストランナーにインストールされているソフトウェア」を参照してください。

`needs`コンテキスト

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

プロパティ名	種類	説明
`needs.<job id>`	`object`	現在のジョブが依存している1つのジョブ。
`needs.<job id>.result`	`string`	現在のジョブが依存しているジョブの結果。 `success`、`failure`、`cancelled` のいずれかの値をとります。
`needs.<job id>.outputs`	`object`	現在のジョブが依存しているジョブの出力の集合。
`needs.<job id>.outputs.<output name>`	`string`	現在のジョブが依存しているジョブの特定の出力の値。

コンテキスト情報をログに出力するサンプル

各コンテキストでアクセスできる情報を調べるには、次の例のようにワークフローファイルを使用します。

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

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-16.04
    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 は、以下の変換方法で、データ型を数字にキャストします。

種類	結果
Null	`0`
Boolean	`true`は`1`を返します。 `false`は`0`を返します。
string	正規のJSON数値型からパースされます。それ以外の場合は`NaN`です。注釈: 空の文字列は `0` を返します。
Array	`NaN`
Object	`NaN`

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

関数

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

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

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はGITHUB_WORKSPACEディレクトリに対する相対であり、含められるのはGITHUB_WORKSPACE内のファイルだけです。この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 SHA-256に関する詳しい情報については「SHA-2」を参照してください。

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

サンプル

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

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

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

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" ]が返されます。

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

担当者にお尋ねください

探しているものが見つからなかったでしょうか？

製品

プラットフォーム

サポート

会社