式

注: GitHub ホステッドランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。

式について

式を使用して、ワークフローファイルとアクセスコンテキストで環境変数をプログラ� で設定できます。式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。コンテキストの詳細については、「コンテキスト」を参照してく� さい。

式は、ステップを実行すべきか判断するための 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> }}

リテラル

式の一部としてboolean、null、number、または string データ型を使用できます。

データ型	[リテラル値]
`boolean`	`true` または `false`
`null`	`null`
`number`	JSONでサポートされている任意の数値書式。
`string`	`${{` と `}}` 内に文字列を囲む必要はありません。た� し、そうする� �合は、文字列の周りに単一引用符 (`'`) を使用する必要があります。リテラル単一引用符を使用するには、追� の単一引用符 (`''`) を使用してリテラルの単一引用符をエスケープします。二重引用符 (`"`) で囲むとエラーがスローされます。

例

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

演算子

演算子	説明
`( )`	論理的なグループ化
`[ ]`	インデックス
`.`	プロパティの参照解除
`!`	Not
`<`	より小さい
`<=`	以下
`>`	より大きい
`>=`	以上
`==`	等しい
`!=`	等しくない
`&&`	および
`\|\|`	または

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('Hello world', 'llo') は、true を返します。

オブジェクトフィルターの使用例

イベントに関連する issue に "bug" というラベルがある� �合、contains(github.event.issue.labels.*.name, 'bug') は true を返します。

詳しくは、「オブジェクトフィルター」をご覧く� さい。

文字列の配列に一致する例

github.event_name == "push" || github.event_name == "pull_request" と書く代わりに、contains() と fromJson() を使って、文字列の配列に item が含まれるかどうかをチェックできます。

たとえば、github.event_name が "push" または "pull_request" の� �合、contains(fromJson('["push", "pull_request"]'), github.event_name) は true を返します。

startsWith

startsWith( searchString, searchValue )

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

例

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

endsWith

endsWith( searchString, searchValue )

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

例

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

format

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

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

例

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

'Hello Mona the Octocat' を返します。

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

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

'{Hello 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オブジェクトを提供したり、環境変数を文字列から変換したりできます。

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

JSONデータ型を返す例

このワークフローでは fromJSON を使い、環境変数を文字列からブール値もしくは整数に変換します。

name: print
on: push
env:
  continue: true
  time: 3
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - continue-on-error: ${{ fromJSON(env.continue) }}
        timeout-minutes: ${{ fromJSON(env.time) }}
        run: echo ...

hashFiles

hashFiles(path)

path パターンに一致するファイル群から単一のハッシュを返します。 1 つの path パターンまたは複数の path のパターンをコンマで区切って指定できます。 path は GITHUB_WORKSPACE ディレクトリに対する相対値であり、GITHUB_WORKSPACE 内のファイルのみを含めることができます。この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 path パターンがどのファイルとも一致しない� �合、空の文字列が返されます。 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 条件では、次の状態チェック関数を式として使用できます。これらの関数のいずれかを含めない限り、既定の success() の状態チェックが適用されます。 if 条件の詳細については、「GitHub Actions のワークフロー構文」を参照してく� さい。

success

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

例

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

常時

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

例

if: ${{ always() }}

取り消し済み

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

例

if: ${{ cancelled() }}

failure

ジョブの前のステップが失敗した� �合に true を返します。依存ジョブのチェーンがある� �合、親要� ジョブが失敗した� �合に failure() は true を返します。

例

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

条件付きのエラー

エラー後に実行するステップの追� 条件を含めることができますが、状態チェック関数を含まない if 条件に自動的に適用される既定の success() の状態チェックをオーバーライドするには、引き続き failure() を含める必要があります。

例

steps:
  ...
  - name: Failing step
    id: demo
    run: exit 1
  - name: The demo step has failed
    if: ${{ failure() && steps.demo.conclusion == 'failure' }}

オブジェクトフィルタ

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

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

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

フィルター fruits.*.name は配列 [ "apple", "orange", "pear" ] を返します。

オブジェクトで * 構文を使用することもできます。たとえば、vegetables という名前のオブジェクトがあるとします。


{
  "scallions":
  {
    "colors": ["green", "white", "red"],
    "ediblePortions": ["roots", "stalks"],
  },
  "beets":
  {
    "colors": ["purple", "red", "gold", "white", "pink"],
    "ediblePortions": ["roots", "stems", "leaves"],
  },
  "artichokes":
  {
    "colors": ["green", "purple", "red", "black"],
    "ediblePortions": ["hearts", "stems", "leaves"],
  },
}

フィルター vegetables.*.ediblePortions の評価結果は次のとおりです。


[
  ["roots", "stalks"],
  ["hearts", "stems", "leaves"],
  ["roots", "stems", "leaves"],
]

オブジェクトは� �序を保持しないため、出力の� �序を保証することはできません。

式

この記事では、次の� �目が扱われます。