コンテキストと式について
プログラムでワークフローファイルの変数を設定したり、コンテキストにアクセスするために、式を利用できます。 式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。 リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。
式は、ステップを実行すべきか判断するための 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> }}
コンテキスト
コンテキストは、ワークフローの実行、ランナーの環境、ジョブ、ステップに関する情報にアクセスする方法です。 コンテキストは式の構文を使用します。
${{ <context> }}
コンテキスト名 | 種類 | 説明 |
---|---|---|
github | オブジェクト | ワークフロー実行に関する情報。 詳しい情報については、「github コンテキスト」を参照してください。 |
env | オブジェクト | ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 詳しい情報についてはenv コンテキストを参照してください。 |
job | オブジェクト | 現在実行中のジョブに関する情報。 詳しい情報については、「job コンテキスト」を参照してください。 |
steps | オブジェクト | このジョブで実行されているステップに関する情報。 詳しい情報については、「steps コンテキスト」を参照してください。 |
runner | オブジェクト | 現在のジョブを実行している runner に関する情報。 詳しい情報についてはrunner コンテキストを参照してください。 |
secrets | オブジェクト | シークレットへのアクセスを有効にします。 シークレットに関する詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。 |
strategy | オブジェクト | 現在のジョブに関して設定されたstrategyパラメータおよび情報にアクセスできます。 strategyパラメータには、fail-fast 、job-index 、job-total 、max-parallel があります。 |
matrix | オブジェクト | 現在のジョブに対して決定したmatrixパラメータにアクセスできます。 例えば、os およびnode バージョンでmatrixビルドを設定した場合、matrix コンテキストオブジェクトには現在のジョブのos およびnode バージョンが含まれます。 |
needs | オブジェクト | 現在のジョブの依存関係として定義されたすべてのジョブの出力へのアクセスを可能にします。 詳しい情報についてはneeds コンテキストを参照してください。 |
式の一部として、次の 2 つの構文のうちいずれかを使用してコンテキストにアクセスすることができます。
- インデックス構文:
github['sha']
- プロパティ参照外しの構文:
github.sha
プロパティ参照外しの構文を使用するには、プロパティ名に次の条件が必要です。
a-Z
または_
で始まる。a-Z
、0-9
、-
、または_
が続く。
Determining when to use contexts
GitHub Actions includes a collection of variables called contexts and a similar collection of variables called default environment variables. These variables are intended for use at different points in the workflow:
- Default environment variables: These variables exist only on the runner that is executing your job. 詳しい情報については、「デフォルトの環境変数」を参照してください。
- Contexts: You can use most contexts at any point in your workflow, including when default environment variables would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional
if
keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such asrunner.os
. 詳細については、「コンテキスト」を参照してください。
The following example demonstrates how these different types of environment variables can be used together in a job:
name: CI
on: push
jobs:
prod-check:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- run: echo "Deploying to production server on branch $GITHUB_REF"
In this example, the if
statement checks the github.ref
context to determine the current branch name; if the name is refs/heads/main
, then the subsequent steps are executed. The if
check is processed by GitHub Actions, and the job is only sent to the runner if the result is true
. Once the job is sent to the runner, the step is executed and refers to the $GITHUB_REF
environment variable from the runner.
github
コンテキスト
github
コンテキストは、ワークフローの実行および、その実行をトリガーしたイベントの情報を含みます。 ほとんどの github
コンテキストデータは、環境変数で読み取ることができます。 環境変数に関する詳しい情報については、「環境変数の利用」を参照してください。
警告: github
コンテキスト全体を使う場合には、github.token
のようなセンシティブな情報が含まれていることを忘れないようにしてください。 GitHubは、シークレットがコンソールに出力される際にはマスクしますが、コンテキストをエクスポートしたりプリントしたりするときには注意が必要です。
プロパティ名 | 種類 | 説明 |
---|---|---|
github | オブジェクト | ワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。 |
github.action | string | 現在実行中のアクションの名前。 GitHubは、現在のステップがステップを実行する際に、特殊なキャラクターを削除するか、run という名前を使います。 同じジョブの中で同じアクションを複数回使う場合、名前には順番に番号が加えられます。 たとえば、実行する最初のスクリプトの名前はrun1 で、2番目のスクリプトの名前はrun2 というようになります。 同様に、actions/checkout の2回目の呼び出しはactionscheckout2 となります。 |
github.action_path | string | アクションが置かれているパス。 このパスを使用して、アクションと同じリポジトリにあるファイルに簡単にアクセスできます。 この属性は、複合実行ステップアクションでのみサポートされています。 |
github.actor | string | ワークフローの実行を開始したユーザのログイン。 |
github.base_ref | string | ワークフローの実行における base_ref またはプルリクエストのターゲットブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。 |
github.event | オブジェクト | webhook ペイロードの完全なイベント。 詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。 このコンテキストを使用して、イベントの個々のプロパティにアクセスできます。 |
github.event_name | string | ワークフローの実行をトリガーしたイベントの名前。 |
github.event_path | string | ランナー上の完全なイベントwebhookペイロードへのパス。 |
github.head_ref | string | ワークフローの実行における head_ref またはプルリクエストのソースブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。 |
github.job | string | 現在のジョブのjob_id 。 |
github.ref | string | ワークフローの実行をトリガーしたブランチまたはタグ ref。 ブランチの場合、これは refs/heads/<branch_name> の形式で、タグの場合は refs/tags/<tag_name> です。 |
github.repository | string | 所有者およびリポジトリの名前。 Codertocat/Hello-World などです。 |
github.repository_owner | string | リポジトリのオーナーの名前。 たとえばCodertocat 。 |
github.run_id | string | リポジトリ内でユニークな各実行に対する番号。 この番号は、ワークフローの実行をやり直しても変化しません、 |
github.run_number | string | リポジトリ内の特定のワークフローの各実行に対するユニークな番号。 この番号は、ワークフローの最初の実行時に1で始まり、新たな実行ごとにインクリメントされます。 この番号は、ワークフローの実行をやり直しても変化しません、 |
github.sha | string | ワークフローの実行をトリガーしたコミット SHA。 |
github.token | string | リポジトリにインストールされたGitHub Appの代わりに認証するためのトークン。 これは機能的にGITHUB_TOKEN シークレットに等価です。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。 |
github.workflow | string | ワークフローの名前。 ワークフローファイルで name を指定していない場合、このプロパティの値は、リポジトリ内にあるワークフローファイルのフルパスになります。 |
github.workspace | string | checkout アクションを使う際の、ステップにとってのデフォルトのワーキングディレクトリであり、リポジトリのデフォルトの場所です。 |
env
コンテキスト
env
コンテキストには、ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 ワークフローでの環境変数の設定に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。
env
の構文で、ワークフローファイル中の環境変数の値を利用できます。 You can use the env
context in the value of any key in a step except for the id
and uses
keys. ステップの構文に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。
ランナー中で環境変数の値を使いたい場合は、ランナーのオペレーティングシステムで環境変数を読み取る通常の方法を使ってください。
プロパティ名 | 種類 | 説明 |
---|---|---|
env | オブジェクト | このコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。 |
env.<env_name> | string | 特定の環境変数の値。 |
job
コンテキスト
job
コンテキストは、現在実行中のジョブに関する情報を含みます。
プロパティ名 | 種類 | 説明 |
---|---|---|
ジョブ | オブジェクト | このコンテキストは、実行しているジョブごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。 |
job.container | オブジェクト | ジョブのコンテナに関する情報。 コンテナに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。 |
job.container.id | string | コンテナの ID。 |
job.container.network | string | コンテナネットワークの ID。 runner は、コンテナ内のすべてのジョブに使用されるネットワークを作成します。 |
job.services | オブジェクト | ジョブのために作成されたサービスコンテナ。 サービスコンテナに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。 |
job.services.<service id>.id | string | サービスコンテナの ID。 |
job.services.<service id>.network | string | サービスコンテナネットワークの ID。 runner は、コンテナ内のすべてのジョブに使用されるネットワークを作成します。 |
job.services.<service id>.ports | オブジェクト | サービスコンテナの公開ポート。 |
job.status | string | ジョブの現在の状態。 success 、failure 、cancelled のいずれかの値をとります。 |
steps
コンテキスト
steps
コンテキストは、すでに実行中のジョブ内のステップに関する情報を含みます。
プロパティ名 | 種類 | 説明 |
---|---|---|
steps | オブジェクト | このコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。 |
steps.<step id>.outputs | オブジェクト | ステップに定義された出力のセット。 詳しい情報については、「GitHub Actions のメタデータ構文」を参照してください。 |
steps.<step id>.conclusion | string | continue-on-error が適用された後に完了したステップの結果。 success 、failure 、cancelled 、skipped のいずれかの値をとります。 continue-on-error のステップが失敗すると、outcome はfailure になりますが、最終的なconclusion はsuccess になります。 |
steps.<step id>.outcome | string | continue-on-error が適用される前の完了したステップの結果。 success 、failure 、cancelled 、skipped のいずれかの値をとります。 continue-on-error のステップが失敗すると、outcome はfailure になりますが、最終的なconclusion はsuccess になります。 |
steps.<step id>.outputs.<output name> | string | 特定の出力の値。 |
runner
コンテキスト
runner
コンテキストには、現在のジョブを実行しているランナーに関する情報が含まれています。
プロパティ名 | 種類 | 説明 |
---|---|---|
runner.os | string | ジョブを実行しているランナーのオペレーティングシステム。 取り得る値はLinux 、Windows 、macOS のいずれか。 |
runner.temp | string | ランナー用のテンポラリディレクトリのパス。 このディレクトリは、セルフホストランナーの場合であっても、各ジョブの開始時点では空であることが保証されています。 |
runner.tool_cache | string | GitHubホストランナーにプレインストールされているいくつかのツールを含むディレクトリのパス。 詳しい情報については、「GitHub ホストランナーの仕様」を参照してください。 |
needs
コンテキスト
needs
コンテキストは、現在のジョブの依存関係として定義されたすべてのジョブからの出力を含みます。 ジョブの依存関係の定義に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。
プロパティ名 | 種類 | 説明 |
---|---|---|
needs.<job id> | オブジェクト | 現在のジョブが依存している1つのジョブ。 |
needs.<job id>.outputs | オブジェクト | 現在のジョブが依存しているジョブの出力の集合。 |
needs.<job id>.outputs.<output name> | string | 現在のジョブが依存しているジョブの特定の出力の値。 |
needs.<job id>.result | string | 現在のジョブが依存しているジョブの結果。 success 、failure 、cancelled 、skipped のいずれかの値をとります。 |
コンテキスト情報をログに出力するサンプル
各コンテキストでアクセスできる情報を調べるには、次の例のようにワークフローファイルを使用します。
警告: github
コンテキスト全体を使う場合には、github.token
のようなセンシティブな情報が含まれていることを忘れないようにしてください。 GitHubは、シークレットがコンソールに出力される際にはマスクしますが、コンテキストをエクスポートしたりプリントしたりするときには注意が必要です。
.github/workflows/main.yml
on: push
jobs:
one:
runs-on: ubuntu-latest
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
run: echo "$GITHUB_CONTEXT"
- name: Dump job context
env:
JOB_CONTEXT: ${{ toJson(job) }}
run: echo "$JOB_CONTEXT"
- name: Dump steps context
env:
STEPS_CONTEXT: ${{ toJson(steps) }}
run: echo "$STEPS_CONTEXT"
- name: Dump runner context
env:
RUNNER_CONTEXT: ${{ toJson(runner) }}
run: echo "$RUNNER_CONTEXT"
- name: Dump strategy context
env:
STRATEGY_CONTEXT: ${{ toJson(strategy) }}
run: echo "$STRATEGY_CONTEXT"
- name: Dump matrix context
env:
MATRIX_CONTEXT: ${{ toJson(matrix) }}
run: echo "$MATRIX_CONTEXT"
リテラル
式の一部として、boolean
、null
、number
、またはstring
のデータ型を使用できます。 boolean のリテラルは大文字と小文字を区別しないので、true
も True
も使用できます。
データ型 | リテラル値 |
---|---|
boolean | true または false |
null | null |
number | JSONでサポートされている任意の数値書式。 |
string | 一重引用符で囲む必要があります。 一重引用符そのものを使用するには、一重引用符でエスケープしてください。 |
サンプル
env:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99-e2 }}
myString: ${{ 'Mona the Octocat' }}
myEscapedString: ${{ 'It''s open source!' }}
演算子
演算子 | 説明 |
---|---|
( ) | 論理グループ化 |
[ ] | インデックス |
. | プロパティ参照外し |
! | 否定 |
< | 小なり |
<= | 以下 |
> | 大なり |
>= | 以上 |
== | 等しい |
!= | 等しくない |
&& | 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')
文字列の使用例
contains('Hello world', 'llo')
は、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
) の数に制限はありません。 中括弧はダブルスペースでエスケープします。
サンプル
'Hello Mona the Octocat' を返します
format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')
括弧をエスケープするサンプル
'{Hello Mona the Octocat!}'を返します。
format('{{Hello {0} {1} {2}!}}', '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のマトリックスを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
hashFiles
hashFiles(path)
path
パターンにマッチするファイル群から単一のハッシュを返します。 単一の path
パターンまたはコンマで区切られた複数の path
パターンを指定できます。 path
はGITHUB_WORKSPACE
ディレクトリに対する相対であり、含められるのはGITHUB_WORKSPACE
内のファイルだけです。 この関数はマッチしたそれぞれのファイルに対するSHA-256ハッシュを計算し、それらのハッシュを使ってファイルの集合に対する最終的なSHA-256ハッシュを計算します。 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
条件では、次のステータスチェック関数を式として使用できます。 if
条件ステータス関数が含まれていない場合、結果は自動的に success()
になります。 if
条件に関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。
success
以前のステップで失敗もしくはキャンセルされたものがない場合にtrue
を返します。
サンプル
steps:
...
- name: The job has succeeded
if: ${{ success() }}
always
常にtrue
を返します。キャンセルされた場合であっても同じです。 クリティカルなエラーによりタスクが実行されない場合は、ジョブやステップも実行されません。 たとえば、ソースの取得に失敗した場合などがそれにあたります。
サンプル
if: ${{ always() }}
cancelled
ワークフローがキャンセルされた場合、true
を返します。
サンプル
if: ${{ cancelled() }}
failure
ジョブの以前のステップのいずれかが失敗したならtrue
を返します。
サンプル
steps:
...
- name: The job has failed
if: ${{ failure() }}
オブジェクトフィルタ
*
構文を使って、フィルタを適用し、コレクション内の一致するアイテムを選択できます。
たとえば、fruits
というオブジェクトの配列を考えます。
[
{ "name": "apple", "quantity": 1 },
{ "name": "orange", "quantity": 2 },
{ "name": "pear", "quantity": 1 }
]
fruits.*.name
というフィルタを指定すると、配列[ "apple", "orange", "pear" ]
が返されます。