ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

GitHub Actions のコンテキストおよび式の構文

ワークフローおよびアクションにおいて、コンテキスト情報へのアクセスおよび式の評価が可能です。

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 For more information, see "GitHub's products."

ここには以下の内容があります:

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.

GitHub Actions の支払いを管理する GitHubは、macOSランナーのホストにMacStadiumを使用しています。

コンテキストと式について

プログラムでワークフローファイルの変数を設定したり、コンテキストにアクセスするために、式を利用できます。 式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。 リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。

式は、ステップを実行すべきか判断するための 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 コンテキスト」を参照してください。
stepsオブジェクトこのジョブで実行されているステップに関する情報。 詳しい情報については、「steps コンテキスト」を参照してください。
runnerオブジェクト現在のジョブを実行している runner に関する情報。 詳しい情報についてはrunnerコンテキストを参照してください。
secretsオブジェクトシークレットへのアクセスを有効にします。 シークレットに関する詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。
strategyオブジェクト現在のジョブに関して設定されたstrategyパラメータおよび情報にアクセスできます。 strategyパラメータには、fail-fastjob-indexjob-totalmax-parallelがあります。
matrixオブジェクト現在のジョブに対して決定したmatrixパラメータにアクセスできます。 例えば、osおよびnode バージョンでmatrixビルドを設定した場合、matrixコンテキストオブジェクトには現在のジョブのosおよびnodeバージョンが含まれます。
needsオブジェクト現在のジョブの依存関係として定義されたすべてのジョブの出力へのアクセスを可能にします。 詳しい情報についてはneedsコンテキストを参照してください。

式の一部として、次の 2 つの構文のうちいずれかを使用してコンテキストにアクセスすることができます。

  • インデックス構文: github['sha']
  • プロパティ参照外しの構文: github.sha

プロパティ参照外しの構文を使用するには、プロパティ名に次の条件が必要です。

  • a-Z または _ で始まる。
  • a-Z0-9-、または_が続く。

github コンテキスト

github コンテキストは、ワークフローの実行および、その実行をトリガーしたイベントの情報を含みます。 ほとんどの github コンテキストデータは、環境変数で読み取ることができます。 環境変数に関する詳しい情報については、「環境変数の利用」を参照してください。

警告: githubコンテキスト全体を使う場合には、github.tokenのようなセンシティブな情報が含まれていることを忘れないようにしてください。 GitHubは、シークレットがコンソールに出力される際にはマスクしますが、コンテキストをエクスポートしたりプリントしたりするときには注意が必要です。

プロパティ名種類説明
githubオブジェクトワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。
github.actionstring現在実行中のアクションの名前。 GitHubは、現在のステップがステップを実行する際に、特殊なキャラクターを削除するか、runという名前を使います。 同じジョブの中で同じアクションを複数回使う場合、名前には順番に番号が加えられます。 たとえば、実行する最初のスクリプトの名前はrun1で、2番目のスクリプトの名前はrun2というようになります。 同様に、actions/checkoutの2回目の呼び出しはactionscheckout2となります。
github.action_pathstringアクションが置かれているパス。 このパスを使用して、アクションと同じリポジトリにあるファイルに簡単にアクセスできます。 この属性は、複合実行ステップアクションでのみサポートされています。
github.actorstringワークフローの実行を開始したユーザのログイン。
github.base_refstringワークフローの実行における base_ref またはプルリクエストのターゲットブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。
github.eventオブジェクトwebhook ペイロードの完全なイベント。 詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。 このコンテキストを使用して、イベントの個々のプロパティにアクセスできます。
github.event_namestringワークフローの実行をトリガーしたイベントの名前。
github.event_pathstringランナー上の完全なイベントwebhookペイロードへのパス。
github.head_refstringワークフローの実行における head_ref またはプルリクエストのソースブランチ。 このプロパティは、ワークフローの実行をトリガーしたイベントが pull_request の場合のみ使用できます。
github.jobstring現在のジョブのjob_id
github.refstringワークフローの実行をトリガーしたブランチまたはタグ ref。 ブランチの場合、これは refs/heads/<branch_name> の形式で、タグの場合は refs/tags/<tag_name> です。
github.repositorystring所有者およびリポジトリの名前。 Codertocat/Hello-Worldなどです。
github.repository_ownerstringリポジトリのオーナーの名前。 たとえばCodertocat
github.run_idstringリポジトリ内でユニークな各実行に対する番号。 この番号は、ワークフローの実行をやり直しても変化しません、
github.run_numberstringリポジトリ内の特定のワークフローの各実行に対するユニークな番号。 この番号は、ワークフローの最初の実行時に1で始まり、新たな実行ごとにインクリメントされます。 この番号は、ワークフローの実行をやり直しても変化しません、
github.shastringワークフローの実行をトリガーしたコミット SHA。
github.tokenstringリポジトリにインストールされたGitHub Appの代わりに認証するためのトークン。 これは機能的にGITHUB_TOKENシークレットに等価です。 詳しい情報については「GITHUB_TOKENでの認証」を参照してください。
github.workflowstringワークフローの名前。 ワークフローファイルで name を指定していない場合、このプロパティの値は、リポジトリ内にあるワークフローファイルのフルパスになります。
github.workspacestringcheckoutアクションを使う際の、ステップにとってのデフォルトのワーキングディレクトリであり、リポジトリのデフォルトの場所です。

envコンテキスト

envコンテキストには、ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。 ワークフローでの環境変数の設定に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

envの構文で、ワークフローファイル中の環境変数の値を利用できます。 ランナー中で環境変数の値を使いたい場合は、ランナーのオペレーティングシステムで環境変数を読み取る通常の方法を使ってください。

envwith及びnameキーの値の中で、あるいはステップのif条件の中でのみ使えます。 ステップの構文に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

プロパティ名種類説明
envオブジェクトこのコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
env.<env name>string特定の環境変数の値。

job コンテキスト

job コンテキストは、現在実行中のジョブに関する情報を含みます。

プロパティ名種類説明
ジョブオブジェクトこのコンテキストは、実行しているジョブごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
job.containerオブジェクトジョブのコンテナに関する情報。 コンテナに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。
job.container.idstringコンテナの ID。
job.container.networkstringコンテナネットワークの ID。 runner は、コンテナ内のすべてのジョブに使用されるネットワークを作成します。
job.servicesオブジェクトジョブのために作成されたサービスコンテナ。 サービスコンテナに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。
job.services.<service id>.idstringサービスコンテナの ID。
job.services.<service id>.networkstringサービスコンテナネットワークの ID。 runner は、コンテナ内のすべてのジョブに使用されるネットワークを作成します。
job.services.<service id>.portsオブジェクトサービスコンテナの公開ポート。
job.statusstringジョブの現在の状態。 successfailurecancelled のいずれかの値をとります。

steps コンテキスト

steps コンテキストは、すでに実行中のジョブ内のステップに関する情報を含みます。

プロパティ名種類説明
stepsオブジェクトこのコンテキストは、ジョブのステップごとに異なります。 このコンテキストには、ジョブのあらゆるステップからアクセスできます。
steps.<step id>.outputsオブジェクトステップに定義された出力のセット。 詳しい情報については、「GitHub Actions のメタデータ構文」を参照してください。
steps.<step id>.conclusionstringcontinue-on-errorが適用された後に完了したステップの結果。 successfailurecancelledskippedのいずれかの値をとります。 continue-on-errorのステップが失敗すると、outcomefailureになりますが、最終的なconclusionsuccessになります。
steps.<step id>.outcomestringcontinue-on-errorが適用される前の完了したステップの結果。 successfailurecancelledskippedのいずれかの値をとります。 continue-on-errorのステップが失敗すると、outcomefailureになりますが、最終的なconclusionsuccessになります。
steps.<step id>.outputs.<output name>string特定の出力の値。

runnerコンテキスト

runnerコンテキストには、現在のジョブを実行しているランナーに関する情報が含まれています。

プロパティ名種類説明
runner.osstringジョブを実行しているランナーのオペレーティングシステム。 取り得る値はLinuxWindowsmacOSのいずれか。
runner.tempstringランナー用のテンポラリディレクトリのパス。 このディレクトリは、セルフホストランナーの場合であっても、各ジョブの開始時点では空であることが保証されています。
runner.tool_cachestringGitHubホストランナーにプレインストールされているいくつかのツールを含むディレクトリのパス。 詳しい情報については、「GitHub ホストランナーの仕様」を参照してください。

needsコンテキスト

needsコンテキストは、現在のジョブの依存関係として定義されたすべてのジョブからの出力を含みます。 ジョブの依存関係の定義に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

プロパティ名種類説明
needs.<job id>オブジェクト現在のジョブが依存している1つのジョブ。
needs.<job id>.outputsオブジェクト現在のジョブが依存しているジョブの出力の集合。
needs.<job id>.outputs.<output name>string現在のジョブが依存しているジョブの特定の出力の値。
needs.<job id>.resultstring現在のジョブが依存しているジョブの結果。 successfailurecancelledskippedのいずれかの値をとります。

コンテキスト情報をログに出力するサンプル

各コンテキストでアクセスできる情報を調べるには、次の例のようにワークフローファイルを使用します。

警告: githubコンテキスト全体を使う場合には、github.tokenのようなセンシティブな情報が含まれていることを忘れないようにしてください。 GitHubは、シークレットがコンソールに出力される際にはマスクしますが、コンテキストをエクスポートしたりプリントしたりするときには注意が必要です。

.github/ワークフロー/メイン.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"

リテラル

式の一部として、booleannullnumber、またはstringのデータ型を使用できます。 boolean のリテラルは大文字と小文字を区別しないので、trueTrue も使用できます。

データ型リテラル値
booleantrue または false
nullnull
numberJSONでサポートされている任意の数値書式。
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
    論理値true1を返します。
    false0を返します。
    文字列型正規のJSON数値型からパースされます。それ以外の場合はNaNです。
    注釈: 空の文字列は 0 を返します。
    配列NaN
    オブジェクトNaN
  • ある NaN を、別の NaN と比較すると、true は返ってきません。 詳しい情報については、「NaN Mozilla ドキュメント」を参照してください。

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

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

関数

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

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

contains

contains( search, item )

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

配列の利用例

contains(github.event.issue.labels.*.name, 'bug')

文字列の使用例

contains('Hello world', 'llo') は、true を返します。

startsWith

startsWith( searchString, searchValue )

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

サンプル

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

endsWith

endsWith( searchString, searchValue )

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

サンプル

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

format

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

string の値を、変数 replaceValueN で置換します。 string の変数は、{N} という構文で指定します。ここで N は整数です。 少なくとも、replaceValuestring を 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 パターンを指定できます。 pathGITHUB_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" ]が返されます。

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.