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

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の製品」を参照してください。

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

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

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

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

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

${{ <expression> }}

When you use expressions in an if conditional, you do not need to use the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression. if条件の詳細については、「GitHub Actionsのためのワークフローの構文」を参照してください。

if 条件内の式の例

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

環境変数の設定例

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

コンテキスト

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

${{ <context> }}

コンテキスト名 種類 説明
github オブジェクト ワークフロー実行に関する情報。 詳しい情報については、「github コンテキスト」を参照してください。
env object ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 詳しい情報についてはenvコンテキストを参照してください。
job オブジェクト 現在実行中のジョブに関する情報。 詳しい情報については、「job コンテキスト」を参照してください。
steps オブジェクト このジョブで実行されているステップに関する情報。 詳しい情報については、「steps コンテキスト」を参照してください。
runner object 現在のジョブを実行している runner に関する情報。 詳しい情報についてはrunnerコンテキストを参照してください。
secrets object リポジトリのシークレットセットにアクセスできます。 シークレットに関する詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。
strategy オブジェクト 現在のジョブに関して設定されたstrategyパラメータおよび情報にアクセスできます。 strategyパラメータには、fail-fastjob-indexjob-totalmax-parallelがあります。
matrix object 現在のジョブに対して決定した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 object ワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。
github.event オブジェクト webhook ペイロードの完全なイベント。 詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。
github.event_path string ランナー上の完全なイベントwebhookペイロードへのパス。
github.workflow string ワークフローの名前。 ワークフローファイルで 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_number 文字列型 A 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 string ワークフローの実行を開始したユーザのログイン。
github.repository string 所有者およびリポジトリの名前。 Codertocat/Hello-Worldなどです。
github.event_name 文字列型 ワークフローの実行をトリガーしたイベントの名前。
github.sha string ワークフローの実行をトリガーしたコミット SHA。
github.ref string ワークフローの実行をトリガーしたブランチまたはタグ ref。
github.head_ref string ワークフローの実行における head_ref またはプルリクエストのソースブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。
github.base_ref 文字列型 ワークフローの実行における base_ref またはプルリクエストのターゲットブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。
github.token 文字列型 リポジトリにインストールされたGitHub Appの代わりに認証するためのトークン。 これは機能的にGITHUB_TOKENシークレットに等価です。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。
github.workspace 文字列型 checkoutアクションを使う際の、ステップにとってのデフォルトのワーキングディレクトリであり、リポジトリのデフォルトの場所です。
github.action string 現在実行中のアクションの名前。 GitHubは、現在のステップがステップを実行する際に、特殊なキャラクターを削除するか、runという名前を使います。 同じジョブの中で同じアクションを複数回使う場合、名前には順番に番号が加えられます。 たとえば、実行する最初のスクリプトの名前はrun1で、2番目のスクリプトの名前はrun2というようになります。 同様に、actions/checkoutの2回目の呼び出しはactionscheckout2となります。

envコンテキスト

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

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

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

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

job コンテキスト

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

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

steps コンテキスト

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

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

runnerコンテキスト

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

プロパティ名 説明
os string ジョブを実行しているランナーのオペレーティングシステム。 取り得る値はLinuxWindowsmacOSのいずれか。
temp string ランナー用のテンポラリディレクトリのパス。 このディレクトリは、セルフホストランナーの場合であっても、各ジョブの開始時点では空であることが保証されています。
tool_cache string 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 も使用できます。

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

サンプル

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

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

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

関数

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

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

contains

contains( searchString, searchValue )

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

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( element, optionalElem )

element の値としては、配列または文字列型を設定できます。 element の値は、すべて文字列型に連結されます。 optionalElem を指定すると、その値が element の末尾に付加されます。 値を文字列にキャストします。

配列を使用するサンプル

join(['Hello', 'Mona', 'the'], 'Octocat') は、'Hello Mona the Octocat' を返します

文字列型を使用するサンプル

join('Hello', 'world!') は、'Hello world!' を返します

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

ジョブの前のステップが成功した場合、true を返します。

steps:
  - name: my first step
    if: success()

always

条件を強制的に true として評価します (キャンセルした場合を含む)。 クリティカルなエラーによりタスクが実行されない場合は、ジョブやステップも実行されません。 たとえば、ソースの取得に失敗した場合などがそれにあたります。

if: always()

cancelled

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

if: cancelled()

failure

前のステップまたはジョブが失敗した場合、true を返します。

サンプル
steps:
  - name: my first step
    if: failure()

オブジェクトフィルタ

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

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

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

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

担当者にお尋ねください

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

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