ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

Context and expression syntax for GitHub Actions

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

GitHub ActionsはGitHub Free、GitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. 詳しい情報については「GitHubの製品」を参照してください。

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

About contexts and expressions

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

式は、ステップを実行すべきか判断するための 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オブジェクトワークフロー実行に関する情報。 詳しい情報については、「github コンテキスト」を参照してください。
envobjectワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 詳しい情報についてはenvコンテキストを参照してください。
jobオブジェクト現在実行中のジョブに関する情報。 詳しい情報については、「job コンテキスト」を参照してください。
stepsobjectこのジョブで実行されているステップに関する情報。 詳しい情報については、「steps コンテキスト」を参照してください。
runnerオブジェクト現在のジョブを実行している runner に関する情報。 詳しい情報についてはrunnerコンテキストを参照してください。
secretsオブジェクトリポジトリのシークレットセットにアクセスできます。 シークレットに関する詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。
strategyobject現在のジョブに関して設定されたstrategyパラメータおよび情報にアクセスできます。 strategyパラメータには、fail-fastjob-indexjob-totalmax-parallelがあります。
matrixオブジェクト現在のジョブに対して決定したmatrixパラメータにアクセスできます。 例えば、osおよびnode バージョンでmatrixビルドを設定した場合、matrixコンテキストオブジェクトには現在のジョブのosおよびnodeバージョンが含まれます。

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

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

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

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

github コンテキスト

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

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

プロパティ名種類説明
githubオブジェクトワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。
github.eventオブジェクトwebhook ペイロードの完全なイベント。 詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。
github.event_pathstringランナー上の完全なイベントwebhookペイロードへのパス。
github.workflowstringワークフローの名前。 ワークフローファイルで name を指定していない場合、このプロパティの値は、リポジトリ内にあるワークフローファイルのフルパスになります。
github.run_id文字列型A unique number for each run within a repository. This number does not change if you re-run the workflow run.
github.run_numberstringA unique number for each run of a particular workflow in a repository. This number begins at 1 for the workflow's first run, and increments with each new run. This number does not change if you re-run the workflow run.
github.actor文字列型ワークフローの実行を開始したユーザのログイン。
github.repository文字列型所有者およびリポジトリの名前。 Codertocat/Hello-Worldなどです。
github.event_namestringワークフローの実行をトリガーしたイベントの名前。
github.shastringワークフローの実行をトリガーしたコミット SHA。
github.refstringワークフローの実行をトリガーしたブランチまたはタグ ref。
github.head_refstringワークフローの実行における head_ref またはプルリクエストのソースブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。
github.base_ref文字列型ワークフローの実行における base_ref またはプルリクエストのターゲットブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。
github.tokenstringリポジトリにインストールされたGitHub Appの代わりに認証するためのトークン。 これは機能的にGITHUB_TOKENシークレットに等価です。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。
github.workspace文字列型checkoutアクションを使う際の、ステップにとってのデフォルトのワーキングディレクトリであり、リポジトリのデフォルトの場所です。
github.action文字列型現在実行中のアクションの名前。 GitHubは、現在のステップがステップを実行する際に、特殊なキャラクターを削除するか、runという名前を使います。 同じジョブの中で同じアクションを複数回使う場合、名前には順番に番号が加えられます。 たとえば、実行する最初のスクリプトの名前はrun1で、2番目のスクリプトの名前はrun2というようになります。 同様に、actions/checkoutの2回目の呼び出しはactionscheckout2となります。

envコンテキスト

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

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

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

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

job コンテキスト

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

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

steps コンテキスト

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

プロパティ名種類説明
stepsobjectこのコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
steps.<step id>.outputsオブジェクトステップに定義された出力のセット。 詳しい情報については、「GitHub Actions のメタデータ構文」を参照してください。
steps.<step id>.outputs.<output name>string特定の出力の値。

runnerコンテキスト

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

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

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

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

警告: 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"

リテラル

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

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

サンプル

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
`

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

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

    種類結果
    ヌル0
    論理値true1を返します。
    false0を返します。
    文字列正規のJSON数値型からパースされます。それ以外の場合はNaNです。
    注釈: 空の文字列は 0 を返します。
    ArrayNaN
    オブジェクトNaN
  • ある NaN を、別の NaN と比較すると、true は返ってきません。 詳しい情報については、「NaN Mozilla ドキュメント」を参照してください。

  • GitHub は、文字列を比較する際に大文字と小文字を区別しません。

  • オブジェクトおよび配列は、同じインスタンスの場合にのみ等しいとみなされます。

関数

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

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

contains

contains( search, item )

Returns true if search contains item. If search is an array, this function returns true if the item is an element in the array. If search is a string, this function returns true if the item is a substring of search. この関数は大文字と小文字を区別しません。 値を文字列にキャストします。

Example using an array

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

Example using a string

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

startsWith

startsWith( searchString, searchValue )

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

サンプル

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

endsWith

endsWith( searchString, searchValue )

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

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

format

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

string の値を、変数 replaceValueN で置換します。 string の変数は、{N} という構文で指定します。ここで N は整数です。 少なくとも、replaceValuestring を 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 )

The value for array can be an array or a string. All values in array are concatenated into a string. If you provide optionalSeparator, it is inserted between the concatenated values. Otherwise, the default separator , is used. 値を文字列にキャストします。

join(github.event.issue.labels.*.name, ', ') may return 'bug, help wanted'

toJson

toJSON(value)

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

サンプル

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

hashFiles

hashFiles(path)

pathパターンにマッチするファイル群から単一のハッシュを返します。 pathGITHUB_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

Returns true when none of the previous steps have failed or been canceled.

サンプル
steps:
  ...
  - name: The job has succeeded
    if: success()

always

Always returns true, even when canceled. クリティカルなエラーによりタスクが実行されない場合は、ジョブやステップも実行されません。 たとえば、ソースの取得に失敗した場合などがそれにあたります。

if: always()

cancelled

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

サンプル
if: cancelled()

failure

Returns true when any previous step of a job fails.

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

担当者にお尋ねください

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

弊社にお問い合わせください