注: 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"],
]
オブジェクトは� �序を保持しないため、出力の� �序を保証することはできません。