Expressions

About expressions

You can use expressions to programmatically set environment variables in workflow files and access contexts. 式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。 リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。 For more information about contexts, see "Contexts."

式は、ステップを実行すべきか判断するための 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	You don't need to enclose strings in ${{ and }}. However, if you do, you must use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). Wrapping with double quotes (") will throw an error.

サンプル

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!' }}

演算子

演算子	説明
( )	論理グループ化
[ ]	インデックス
から実行されます。	Property de-reference
!	否定
<	小なり
<=	以下
>	大なり
>=	以上
==	等しい
!=	等しくない
&&	AND
||	OR

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

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

  種類	結果
  ヌル	0
  論理値	trueは1を返します。 falseは0を返します。
  文字列型	正規のJSON数値型からパースされます。それ以外の� �合はNaNです。 注釈: 空の文字列は 0 を返します。
  配列	NaN
  オブジェクト	NaN

• ある NaN を、別の NaN と比較すると、true は返ってきません。 詳しい情� �については、「NaN Mozilla ドキュメント」を参照してく� さい。

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

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

関数

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

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

contains

contains( search, item )

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

配列の利用例

contains(github.event.issue.labels.*.name, 'bug') returns whether the issue related to the event has a label "bug".

文字列の使用例

contains('Hello world', 'llo') returns true.

startsWith

startsWith( searchString, searchValue )

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

サンプル

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

endsWith

endsWith( searchString, searchValue )

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

サンプル

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

format

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

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

サンプル

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

Returns 'Hello Mona the Octocat'.

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

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

Returns '{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パターンにマッチするファイル群から単一のハッシュを返します。 単一の path パターンまたはコンマで区切られた複数の path パターンを指定できます。 pathはGITHUB_WORKSPACEディレクトリに対する相対であり、含められるのはGITHUB_WORKSPACE内のファイル� けです。 この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 If the path pattern does not match any files, this returns an empty string. 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')

Check Functions

if 条件では、次のステータスチェック関数を式として使用できます。 A default status check of success() is applied unless you include one of these functions. For more information about if conditionals, see "Workflow syntax for GitHub Actions".

success

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

サンプル

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

always

Causes the step to always execute, and returns true, even when canceled. クリティカルなエラーによりタスクが実行されない� �合は、ジョブやステップも実行されません。 たとえば、ソースの取得に失敗した� �合などがそれにあたります。

サンプル

if: ${{ always() }}

cancelled

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

サンプル

if: ${{ cancelled() }}

failure

ジョブの以前のステップのいずれかが失敗したならtrueを返します。 If you have a chain of dependent jobs, failure() returns true if any ancestor job fails.

サンプル

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

failure with conditions

You can include extra conditions for a step to run after a failure, but you must still include failure() to override the default status check of success() that is automatically applied to if conditions that don't contain a status check function.

サンプル

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 }
]

The filter fruits.*.name returns the array [ "apple", "orange", "pear" ].

You may also use the * syntax on an object. For example, suppose you have an object named 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"],
  },
}

The filter vegetables.*.ediblePortions could evaluate to:

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

Since objects don't preserve order, the order of the output can not be guaranteed.