注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
式について
式を使用して、ワークフロー ファイルとアクセス コンテキストで環境変数をプログラムで設定できます。 式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。 リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。 コンテキストについて詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。
式は、ステップを実行すべきか判断するための if
条件キーワードをワークフロー ファイル内に記述して使用するのが一般的です。 if
条件が true
の場合は、ステップが実行されます。
ある式を、文字列型として扱うのではなく式として評価するためには、特定の構文を使って GitHub に指示する必要があります。
${{ <expression> }}
注: この規則の例外は、if
句で式を使用する場合です。通常、${{
と }}
を任意で省略することができます。 if
条件式に関する詳細情報は、「GitHub Actions のワークフロー構文」をご覧ください。
警告: ワークフローとアクションを作成するときは、コードが攻撃者からの信頼されていない入力を実行する可能性があるかどうかを常に考慮する必要があります。 攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信頼できない入力として扱うべきです。 詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。
環境変数の設定例
env:
MY_ENV_VAR: ${{ <expression> }}
リテラル
式の一部として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 |
< | より小さい |
<= | 以下 |
> | より大きい |
>= | 以上 |
== | 等しい |
!= | 等しくない |
&& | および |
|| | または |
注:
- GitHub は、文字列を比較するときに大文字と小文字を区別しません。
steps.<step_id>.outputs.<output_name>
は文字列として評価されます。 ある式を、文字列型として扱うのではなく式として評価するためには、特定の構文を使って GitHub に指示する必要があります。詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。- 数値比較では、
fromJSON()
関数を使って文字列を数値に変換できます。fromJSON()
関数について詳しくは、「fromJSON」をご覧ください。
GitHub は、等価性を緩やかに比較します。
-
型が一致しない場合、GitHub は型を強制的に数値とします。 GitHub は、以下の変換方法で、データ型を数字にキャストします。
型 結果 [Null] 0
Boolean true
は1
を返します。
false
は0
を返します。String 正規の JSON 数値形式から解析されます。それ以外の場合は NaN
です。
注: 空の文字列は0
を返します。Array NaN
Object NaN
-
NaN
が関係比較演算子 (>
、<
、>=
、<=
) のオペランドの 1 つである場合、結果は常にfalse
になります。 詳細については、NaN Mozilla ドキュメントを参照してください。 -
GitHub は、文字列を比較する際に大文字と小文字を区別しません。
-
オブジェクトおよび配列は、同じインスタンスの場合にのみ等しいとみなされます。
GitHub には、式で使用できる動作のような三項演算子が用意されています。 この方法で三項演算子を使うと、あり得るオプションごとに個別に if-else ブロックを書かなくても、条件に基づいて環境変数の値を動的に設定できます。
例
env:
MY_ENV_VAR: ${{ github.ref == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }}
この例では、三項演算子を使い、GitHub の参照が refs/heads/main
に設定されているかどうかに基づいて、環境変数 MY_ENV_VAR
の値を設定しています。 そうである場合、変数は value_for_main_branch
に設定されます。 そうでない場合は、value_for_other_branches
に設定されます。
&&
の後の最初の値は真値でなければならないことに注意することが重要です。 それ以外の場合、||
の後の値は常に返されます。
機能
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
の例
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
の例
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
の例
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
を使って次のジョブに渡します。
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
を使い、環境変数を文字列からブール値もしくは整数に変換します。
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
を文字列からブール値に変換し、エラー時に続行するかどうかを判断できます。 同様に、time
環境変数を文字列から整数に変換し、ジョブのタイムアウトを分単位で設定します。
hashFiles
hashFiles(path)
path
パターンに一致するファイル群から単一のハッシュを返します。 1 つの path
パターンまたは複数の path
のパターンをコンマで区切って指定できます。 path
は GITHUB_WORKSPACE
ディレクトリに対する相対値であり、GITHUB_WORKSPACE
内のファイルのみを含めることができます。 この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 path
パターンがどのファイルとも一致しない場合、空の文字列が返されます。 SHA-256 の詳細については、「SHA-2」を参照してください。
パターンマッチング文字を使ってファイル名をマッチさせることができます。 hashFiles
のパターン マッチングは glob パターン マッチングに従っており、Windows では大文字と小文字が区別されません。 サポートされているパターン マッチング文字について詳しくは、@actions/glob
ドキュメントのパターンセクションに関する記事を参照してください。
単一のパターンの例
リポジトリ内の任意の package-lock.json
ファイルと一致します。
hashFiles('**/package-lock.json')
複数のパターンの例
リポジトリ内の任意の package-lock.json
および Gemfile.lock
ファイルのハッシュを作成します。
hashFiles('**/package-lock.json', '**/Gemfile.lock')
ステータスチェック関数
if
条件では、次の状態チェック関数を式として使用できます。 これらの関数のいずれかを含めない限り、既定の success()
の状態チェックが適用されます。 if
条件について詳しくは、「GitHub Actions のワークフロー構文」と「GitHub Actions のメタデータ構文」をご覧ください。
success
これまでの手順がすべて成功した場合は true
を返します。
success
の例
steps:
...
- name: The job has succeeded
if: ${{ success() }}
常時
ステップが常に実行され、キャンセルされた場合でも true
を返します。 always
式は、ジョブが取り消された場合でも実行することが想定されるタスクでまたはステップ レベルで使うのが最適です。 たとえば、always
を使用すると、ジョブがキャンセルされた場合でもログを送信できます。
警告: ソースの取得など、重大なエラーが発生する可能性があるタスクには always
を使用しないでください。そうしないと、タイムアウトになるまでワークフローがハングする可能性があります。成功または失敗に関係なくジョブまたはステップを実行する場合は、推奨される代替手段 if: ${{ !cancelled() }}
を使用してください。
always
の例
if: ${{ always() }}
取り消し済み
ワークフローがキャンセルされた場合に true
を返します。
cancelled
の例
if: ${{ cancelled() }}
failure
ジョブの前のステップが失敗した場合に 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"],
]
オブジェクトは順序を保持しないため、出力の順序を保証することはできません。