ワークフロー内とアクション内で式を評価する

リテラル

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

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

条件の中で、偽の値 (false、0、-0、""、''、null) が false に強制的に適用され、真の値 (true、および偽ではない他の値) が true に強制的に適用されることに注意してください。

リテラルの例

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
`<`	より小さい
`<=`	以下
`>`	より大きい
`>=`	以上
`==`	等しい
`!=`	等しくない
`&&`	And
`\|\|`	または

メモ

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

          `steps.<step_id>.outputs.<output_name>` は文字列として評価されます。 ある式を、文字列型として扱うのではなく式として評価するためには、特定の構文を使って GitHub に指示する必要があります。 詳細については、「[AUTOTITLE](/actions/learn-github-actions/contexts#steps-context)」を参照してください。

数値比較を行おうとする場合は、fromJSON() 関数を使用して文字列を数値に変換することができます。 fromJSON() 関数の詳細については、「fromJSON」を参照してください。

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

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

タイプ	結果
[Null]	`0`
ブール値	`true` は `1` を返します `false` は `0` を返します
String	正規の JSON 数値形式から解析されます。それ以外の場合は `NaN` です。注: 空の文字列は `0` を返します。
Array	`NaN`
Object	`NaN`

NaN が、いずれかの関係比較演算子 (>、<、>=、<=) のオペランドの 1 つである場合、結果は常に false になります。詳細については、NaN Mozilla ドキュメントを参照してください。
GitHub は、文字列を比較する際に大文字と小文字を区別しません。
オブジェクトおよび配列は、同じインスタンスの場合にのみ等しいとみなされます。

Functions

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

タイプ	結果
[Null]	`''`
ブール値	`'true'` または `'false'`
番号	10進数、大きい場合は指数
Array	配列は文字列型に変換されません
Object	オブジェクトは文字列型に変換されません

contains

contains( search, item )

search に item が含まれている場合に true を返します。 search が配列の場合、item が配列内の要素であれば、この関数は true を返します。 search が文字列の場合、item が search の部分文字列であれば、この関数は true を返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。

文字列の使用例

          `contains('Hello world', 'llo')` は `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` の例

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

endsWith

endsWith( searchString, searchValue )

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

`endsWith` の例

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

参加

join( array, optionalSeparator )

array の値には、配列または文字列を指定できます。 array のすべての値が文字列に連結されます。 optionalSeparator を指定した場合は、連結された値の間に挿入されます。それ以外の場合は、既定の区切り記号の , が使用されます。値を文字列にキャストします。

`join` の例

          `join(github.event.issue.labels.*.name, ', ')` では、'bug, help wanted' が返される場合があります

toJSON

toJSON(value)

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

`toJSON` の例

          `toJSON(job)` では、`{ "status": "success" }` が返される場合があります

fromJSON

fromJSON(value)

value に対する JSON オブジェクト、あるいは JSON データ型を返します。この関数を使用すると、JSON オブジェクトを渡して評価された式として提供すること、または、文字列、ブール値、null 値、配列、オブジェクトなど、JSON または JavaScript で表すことができる任意のデータ型を変換することができます。

JSONオブジェクトを返す例

このワークフローは JSON マトリックスを 1 つのジョブに設定し、それを出力と fromJSON を使って次のジョブに渡します。

YAML

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

JSONデータ型を返す例

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

YAML

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 ...

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 ...

ワークフローは、fromJSON() 関数を使用して環境変数 continue を文字列からブール値に変換し、エラーのまま続行する (continue-on-error) かどうかを判断することができます。同様に、これは time 環境変数を文字列から整数型に変換し、ジョブのタイムアウトを分単位で設定します。

path パターンに一致するファイル群から単一のハッシュを返します。 1 つの path パターンまたは複数の path のパターンをコンマで区切って指定できます。 path は GITHUB_WORKSPACE ディレクトリに対する相対値であり、GITHUB_WORKSPACE 内のファイルのみを含めることができます。この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 path パターンがどのファイルとも一致しない場合、空の文字列が返されます。 SHA-256 の詳細については、「SHA-2」を参照してください。

パターンマッチング文字を使ってファイル名をマッチさせることができます。 hashFiles に対応するパターンマッチングは glob パターンマッチングに従っており、Windows では大文字と小文字を区別しません。サポートされているパターンマッチング文字の詳細については、@actions/glob ドキュメントの「Patterns (パターン)」セクションを参照してください。

単一のパターンを使用する例

リポジトリ内の任意の package-lock.json ファイルと一致します。

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

ルートレベルで .js ディレクトリ内にあるすべての src ファイルと比較しますが、src のサブディレクトリを無視します。

hashFiles('/src/*.js')

ルートレベルで .rb ディレクトリ内にあるすべての lib ファイルと比較し、lib のサブディレクトリも比較に含めます。

hashFiles('/lib/**/*.rb')

複数のパターンを使用する例

リポジトリ内の任意の package-lock.json および Gemfile.lock ファイルのハッシュを作成します。

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

ルートレベルで .rb ディレクトリ内にあるすべての lib ファイルのハッシュを作成します。このとき、lib のサブディレクトリを含めますが、foo サブディレクトリ内の .rb ファイルは除外します。

hashFiles('/lib/**/*.rb', '!/lib/foo/*.rb')

ケース

case( pred1, val1, pred2, val2, ..., default )

述語を順番に評価し、 trueに評価される最初の述語に対応する値を返します。一致する述語がない場合は、最後の引数が既定値として返されます。

単一の述語を使用した例

env:
  MY_ENV_VAR: ${{ case(github.ref == 'refs/heads/main', 'production', 'development') }}

ref がMY_ENV_VARされたときにproductionをrefs/heads/mainに設定し、それ以外の場合はdevelopmentに設定します。

複数の述語を使用する例

env:
  MY_ENV_VAR: ${{ case(
    github.ref == 'refs/heads/main', 'production',
    github.ref == 'refs/heads/staging', 'staging',
    startsWith(github.ref, 'refs/heads/feature/'), 'development',
    'unknown'
  ) }}

ブランチに基づいてMY_ENV_VARを設定します。productionのmain、stagingのstaging、developmentで始まるブランチのfeature/、または他のすべてのブランチのunknown。

ステータスチェック関数

if 条件では、次の状態チェック関数を式として使用できます。これらの関数のいずれかを含めない限り、既定の success() の状態チェックが適用されます。 if 条件の詳細については、「GitHub Actions　のワークフロー構文」と「メタデータ構文リファレンス」を参照してください。

if の条件外の場合は、job.status を使用してジョブの状態にアクセスできます。詳しくは、「コンテキストリファレンス」をご覧ください。

成功

これまでの手順がすべて成功した場合は true を返します。

`success` の例

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

常時

ステップが常に実行され、キャンセルされた場合でも true を返します。 always 式は、ジョブが取り消された場合でも実行することが想定されるタスクでまたはステップレベルで使うのが最適です。たとえば、always を使用すると、ジョブがキャンセルされた場合でもログを送信できます。

警告

ソースの取得など、重大なエラーが発生する可能性があるタスクには always を使用しないでください。そうしないと、タイムアウトになるまでワークフローがハングする可能性があります。成功または失敗に関係なくジョブまたはステップを実行する場合は、推奨される代替手段 if: ${{ !cancelled() }} を使用してください。

`always` の例

if: ${{ always() }}

取り消し済み

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

`cancelled` の例

if: ${{ cancelled() }}

失敗

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

`failure` の例

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

条件付きのエラー

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

条件を含む `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"],
]

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

ワークフロー内とアクション内で式を評価する

この記事の内容