# ワークフロー内とアクション内で式を評価する GitHub Actionsで式の情報を検索します。 ## リテラル式の一部として`boolean`、`null`、`number`、または `string` データ型を使用できます。 | データ型 | \[リテラル値] | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `boolean` | | | `true` または `false` | | | `null` | `null` | | `number` | JSONでサポートされている任意の数値書式。 | | `string` | | | `${` と `}` 内に文字列を囲む必要はありません。ただし、そうする場合は、文字列の周りに単一引用符 (`'`) を使用する必要があります。リテラル単一引用符を使用するには、追加の単一引用符 (`''`) を使用してリテラルの単一引用符をエスケープします。二重引用符 (`"`) で囲むとエラーがスローされます。 | | 条件の中で、偽の値 (`false`、`0`、`-0`、`""`、`''`、`null`) が `false` に強制的に適用され、真の値 (`true`、および偽ではない他の値) が `true` に強制的に適用されることに注意してください。 ### リテラルの例 ```yaml 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 | | \|\| | または | > \[!NOTE] > \* > GitHub は、文字列を比較するときに大文字と小文字を区別しません。 > \* > `steps..outputs.` は文字列として評価されます。 > ある式を、文字列型として扱うのではなく式として評価するためには、特定の構文を使って GitHub に指示する必要があります。詳細については、 [AUTOTITLE を](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#steps-context)参照してください。 > > * 数値比較を行おうとする場合は、`fromJSON()` 関数を使用して文字列を数値に変換することができます。 > `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 ドキュメント](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN)を参照してください。 * GitHub は、文字列を比較するときに大文字と小文字を区別しません。 * オブジェクトおよび配列は、同じインスタンスの場合にのみ等しいとみなされます。 ## Functions GitHub には、式で使用できる一連の組み込み関数が用意されています。一部の関数は、比較を行なうために、値を文字列型にキャストします。 GitHub は、次の変換を使用してデータ型を文字列にキャストします。 | タイプ | 結果 | | ---------------------- | ------------------- | | \[Null] | `''` | | ブール値 | | | `'true'` または `'false'` | | | 番号 | 10進数、大きい場合は指数 | | Array | 配列は文字列型に変換されません | | Object | オブジェクトは文字列型に変換されません | ### contains `contains( search, item )` `true` に `search` が含まれている場合に `item` を返します。 `search` が配列の場合、`true` が配列内の要素であれば、この関数は `item` を返します。 `search` が文字列の場合、`true` が `item` の部分文字列であれば、この関数は `search` を返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。 #### 文字列の使用例 `contains('Hello world', 'llo')` は `true` を返します。 #### オブジェクトフィルターの使用例イベントに関連する issue に "bug" というラベルがある場合、`contains(github.event.issue.labels.*.name, 'bug')` は `true` を返します。詳細については、「[オブジェクトフィルター](#object-filters)」を参照してください。 #### 文字列の配列に一致する例 `github.event_name == "push" || github.event_name == "pull_request"` と書く代わりに、`contains()` と `fromJSON()` を使って、文字列の配列に `item` が含まれるかどうかをチェックできます。たとえば、`contains(fromJSON('["push", "pull_request"]'), github.event_name)` が "push" または "pull\_request"、`true` は `github.event_name` を返します。 ### startsWith `startsWith( searchString, searchValue )` `true` が `searchString` で始まる場合は、`searchValue` を返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。 #### `startsWith` の例 `startsWith('Hello world', 'He')` は `true` を返します。 ### endsWith `endsWith( searchString, searchValue )` `true` が `searchString` で終わる場合は、`searchValue` を返します。この関数は大文字と小文字を区別しません。値を文字列にキャストします。 #### `endsWith` の例 `endsWith('Hello world', 'ld')` は `true` を返します。 ### format `format( string, replaceValue0, replaceValue1, ..., replaceValueN)` `string` 内の値を `replaceValueN` 変数に置き換えます。 `string` 内の変数は、`{N}` 構文 (`N` は整数) を使用して指定されます。少なくとも 1 つの `replaceValue` と `string` を指定する必要があります。使用できる変数 (`replaceValueN`) の最大数はありません。中括弧はダブルブレースでエスケープします。 #### `format` の例 ```javascript format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat') ``` 'Hello Mona the Octocat' を返します。 #### 括弧をエスケープするサンプル ```javascript format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat') ``` '{Hello Mona the Octocat!}' を返します。 ### 参加 `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 copy 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 copy 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` 環境変数を文字列から整数型に変換し、ジョブのタイムアウトを分単位で設定します。 ### hashFiles `hashFiles(path)` `path` パターンに一致するファイル群から単一のハッシュを返します。 1 つの `path` パターンまたは複数の `path` のパターンをコンマで区切って指定できます。 `path` は `GITHUB_WORKSPACE` ディレクトリに対する相対値であり、`GITHUB_WORKSPACE` 内のファイルのみを含めることができます。この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 `path` パターンがどのファイルとも一致しない場合、空の文字列が返されます。 SHA-256 の詳細については、「[SHA-2](https://en.wikipedia.org/wiki/SHA-2)」を参照してください。パターンマッチング文字を使ってファイル名をマッチさせることができます。 `hashFiles` に対応するパターンマッチングは glob パターンマッチングに従っており、Windows では大文字と小文字を区別しません。サポートされているパターンマッチング文字の詳細については、[](https://www.npmjs.com/package/@actions/glob#patterns) ドキュメントの「`@actions/glob`」セクションを参照してください。 #### 単一のパターンを使用する例リポジトリ内の任意の `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` のサブディレクトリを含めますが、`.rb` サブディレクトリ内の `foo` ファイルは除外します。 `hashFiles('/lib/**/*.rb', '!/lib/foo/*.rb')` ## ステータスチェック関数 `if` 条件では、次の状態チェック関数を式として使用できます。これらの関数のいずれかを含めない限り、既定の `success()` の状態チェックが適用されます。 `if` 条件の詳細については、「[GitHub Actions　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idif)」と「[メタデータ構文リファレンス](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/metadata-syntax#runsstepsif)」を参照してください。 `if` の条件外の場合は、`job.status` を使用してジョブの状態にアクセスできます。詳しくは、「[コンテキストリファレンス](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#job-context)」をご覧ください。 ### 成功これまでの手順がすべて成功した場合は `true` を返します。 #### `success` の例 ```yaml steps: ... - name: The job has succeeded if: ${{ success() }} ``` ### 常時ステップが常に実行され、キャンセルされた場合でも `true` を返します。 `always` 式は、ジョブが取り消された場合でも実行することが想定されるタスクでまたはステップレベルで使うのが最適です。たとえば、`always` を使用すると、ジョブがキャンセルされた場合でもログを送信できます。 > \[!WARNING] > ソースの取得など、重大なエラーが発生する可能性があるタスクには `always` を使用しないでください。そうしないと、タイムアウトになるまでワークフローがハングする可能性があります。成功または失敗に関係なくジョブまたはステップを実行する場合は、推奨される代替手段 `if: ${{ !cancelled() }}` を使用してください。 #### `always` の例 ```yaml if: ${{ always() }} ``` ### 取り消し済みワークフローがキャンセルされた場合に `true` を返します。 #### `cancelled` の例 ```yaml if: ${{ cancelled() }} ``` ### 失敗ジョブの前のステップが失敗した場合に `true` を返します。依存ジョブのチェーンがある場合、親要素ジョブが失敗した場合に `failure()` は `true` を返します。 #### `failure` の例 ```yaml steps: ... - name: The job has failed if: ${{ failure() }} ``` #### 条件付きのエラーエラー後に実行するステップの追加条件を含めることができますが、状態チェック関数を含まない `failure()` 条件に自動的に適用される既定の `success()` の状態チェックをオーバーライドするには、引き続き `if` を含める必要があります。 ##### 条件を含む `failure` の例 ```yaml steps: ... - name: Failing step id: demo run: exit 1 - name: The demo step has failed if: ${{ failure() && steps.demo.conclusion == 'failure' }} ``` ## オブジェクトフィルタ `*` 構文を使用して、フィルターを適用し、コレクション内の一致する項目を選択できます。たとえば、`fruits` というオブジェクトの配列を考えます。 ```json [ { "name": "apple", "quantity": 1 }, { "name": "orange", "quantity": 2 }, { "name": "pear", "quantity": 1 } ] ``` フィルター `fruits.*.name` は配列 `[ "apple", "orange", "pear" ]` を返します。オブジェクトで `*` 構文を使用することもできます。たとえば、`vegetables` という名前のオブジェクトがあるとします。 ```json { "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` の評価結果は次のとおりです。 ```json [ ["roots", "stalks"], ["hearts", "stems", "leaves"], ["roots", "stems", "leaves"], ] ``` オブジェクトは順序を保持しないため、出力の順序を保証することはできません。