Skip to main content

ワークフローとアクションで式を評価できます。

注: 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> }}

リテラル

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

データ型[リテラル値]
booleantrue または false
nullnull
numberJSONでサポートされている任意の数値書式。
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
    Booleantrue1 を返します。
    false0 を返します。
    String正規の JSON 数値形式から解析されます。それ以外の場合は NaN です。
    注: 空の文字列は 0 を返します。
    ArrayNaN
    ObjectNaN
  • NaN を別の NaN と比較すると、true は返されません。 詳細については、NaN Mozilla ドキュメントを参照してください。

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

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

機能

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

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

contains

contains( search, item )

searchitem が含まれている場合に true を返します。 search が配列の場合、item が配列内の要素であれば、この関数は true を返します。 search が文字列の場合、itemsearch の部分文字列であれば、この関数は 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 )

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

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

endsWith

endsWith( searchString, searchValue )

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

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

format

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

string 内の値を replaceValueN 変数に置き換えます。 string 内の変数は、{N} 構文 (N は整数) を使用して指定されます。 少なくとも 1 つの replaceValuestring を指定する必要があります。 使用できる変数 (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 のパターンをコンマで区切って指定できます。 pathGITHUB_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 のワークフロー構文」および「GitHub 複合アクションのメタデータ構文」を参照してください。

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"],
]

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