記事のバージョン： GitHub.com

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

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

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub AEで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。詳しい情報については「GitHubの製品」を参照してください。

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

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

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

式は、ステップを実行すべきか判断するための if 条件キーワードをワークフローファイル内に記述して使用するのが一般的です。 if条件がtrueになれば、ステップは実行されます。

ある式を、文字列型として扱うのではなく式として評価するためには、特定の構文を使って GitHub に指示する必要があります。

${{ <expression> }}

if条件の中で式を使う場合、式構文(${{ }})を省略できます。これは、式に演算子が含まれていない場合、GitHubが自動的にif条件を式として評価するためです。式に演算子が含まれている場合、明示的に評価されるようマークするためにその式を${{ }}で囲まなければなりません。 if条件の詳細については、「GitHub Actionsのためのワークフローの構文」を参照してください。

警告: ワークフローやアクションを作る際には、攻撃者からの信頼できない入力をコードが実行するかもしれないことを、常に意識しなければなりません。攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信頼できない入力として扱うべきです。詳しい情報については「スクリプトインジェクションのリスクを理解する」を参照してください。

`if` 条件内の式の例

steps:
  - uses: actions/[email protected]
    if: ${{ <expression> }}

環境変数の設定例

env:
  MY_ENV_VAR: ${{ <expression> }}

コンテキスト

コンテキストは、ワークフローの実行、ランナーの環境、ジョブ、ステップに関する情報にアクセスする方法です。コンテキストは式の構文を使用します。

${{ <context> }}

コンテキスト名	種類	説明
`github`	`オブジェクト`	ワークフロー実行に関する情報。詳しい情報については、「`github` コンテキスト」を参照してください。
`env`	`オブジェクト`	ワークフロー、ジョブ、ステップで設定された環境変数が含まれます。詳しい情報については、`env` コンテキストを参照してください。
`job`	`オブジェクト`	現在実行中のジョブに関する情報。詳しい情報については、「`job` コンテキスト」を参照してください。
`steps`	`オブジェクト`	このジョブで実行されているステップに関する情報。詳しい情報については、「`steps` コンテキスト」を参照してください。
`runner`	`オブジェクト`	現在のジョブを実行しているランナーに関する情報。詳しい情報については`runner`コンテキストを参照してください。
`secrets`	`オブジェクト`	シークレットへのアクセスを有効にします。シークレットに関する詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。
`strategy`	`オブジェクト`	現在のジョブに関して設定されたstrategyパラメータおよび情報にアクセスできます。 strategyパラメータには、`fail-fast`、`job-index`、`job-total`、`max-parallel`があります。
`matrix`	`オブジェクト`	現在のジョブに対して決定したmatrixパラメータにアクセスできます。例えば、`os`および`node` バージョンでマトリックスビルドを設定した場合、`matrix`コンテキストオブジェクトには現在のジョブの`os`および`node`バージョンが含まれます。
`needs`	`オブジェクト`	現在のジョブの依存関係として定義されたすべてのジョブの出力へのアクセスを可能にします。詳しい情報については`needs`コンテキストを参照してください。

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

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

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

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

コンテキストを使用する場合の判断

GitHub Actionsは、コンテキストと呼ばれる変数の集合と、デフォルトの環境変数と呼ばれる同様の変数の集合を含みます。これらの変数は、ワークフロー中の様々な場所で利用されることを意図したものです。

デフォルトの環境変数: これらの変数は、ジョブを実行しているランナー上にのみ存在します。詳しい情報については、「デフォルトの環境変数」を参照してください。
コンテキスト: ほとんどのコンテキストはワークフローの任意の場所で利用できます。これは、デフォルトの環境変数が利用できない場所も含みます。たとえば、式の付いたコンテキストを使って、ジョブが実行のためにランナーにまわされる前に初期の処理を行うことができます。これによって、ステップを実行すべきかを判断するために条件のifキーワード付きのコンテキストが利用できるようになります。ジョブが実行されると、runner.osといったように、コンテキスト変数をジョブを実行しているランナーから取り出すこともできます。詳細については、「コンテキスト」を参照してください。

以下の例は、様々な種類の環境変数をジョブの中で合わせて利用できることを示しています。

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"

この例では、if文がgithub.refコンテキストをチェックして現在のブランチ名を判断しています。その名前がrefs/heads/mainであれば、以降のステップが実行されます。このifチェックがGitHub Actionsで処理されたなら、その結果がtrueの場合にのみジョブがランナーに送信されます。ジョブがランナーに送信されると、ステップが実行され、環境変数の$GITHUB_REFをランナーから参照します。

`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のターゲットブランチ。このプロパティは、ワークフローの実行をトリガーするイベントが `pull_request` または `pull_request_target` のいずれかである場合にのみ使用できます。
`github.event`	`オブジェクト`	webhook ペイロードの完全なイベント。詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。このコンテキストを使用して、イベントの個々のプロパティにアクセスできます。
`github.event_name`	`string`	ワークフローの実行をトリガーしたイベントの名前。
`github.event_path`	`string`	ランナー上の完全なイベントwebhookペイロードへのパス。
`github.head_ref`	`string`	ワークフローの実行における `head_ref` またはPull Requestのソースブランチ。このプロパティは、ワークフローの実行をトリガーするイベントが `pull_request` または `pull_request_target` のいずれかである場合にのみ使用できます。
`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の構文で、ワークフローファイル中の環境変数の値を利用できます。 id及びusesキーを除く、step中の任意のキーの値でenvコンテキストを利用できます。ステップの構文に関する詳しい情報については「GitHub Actionsのワークフロー構文」を参照してください。

ランナー中で環境変数の値を使いたい場合は、ランナーのオペレーティングシステムで環境変数を読み取る通常の方法を使ってください。

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

`job` コンテキスト

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。ランナーは、コンテナ内のすべてのジョブに使用されるネットワークを作成します。
`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/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'`
数値	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オブジェクトを提供したり、環境変数を文字列から変換したりできます。

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ハッシュを計算します。 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" ]が返されます。

Jun	JUL	Aug
	08
2020	2021	2022

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

これらのドキュメントを素晴らしいものにするのを手伝ってください！

問題がまだ解決していませんか？