GitHub でコンテキストと式を調べる

  • 10 分

コンテキストは、ワークフローの実行、変数、ランナーの環境、ジョブ、ステップに関する情報にアクセスする方法です。 各コンテキストは、プロパティを含むオブジェクトであり、文字列やその他のオブジェクトにすることができます。

式構文を使用してコンテキストにアクセスできます。 式で使えるのは、リテラル値、コンテキストへの参照、関数の組み合わせです。 リテラル、コンテキストへの参照、および関数を組み合わせるには、演算子を使います。

コンテキスト

ワークフローとアクションを作成するときは、攻撃者によってコードが信頼されていない入力を実行する可能性があるかどうかを常に考慮する必要があります。 攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信頼できない入力として扱うべきです。 詳細については、「 GitHub Actions のセキュリティ強化」を参照してください。

次の表に、GitHub で使用できるコンテキストの例を示します。完全な一覧ではありません。

コンテキスト名 タイプ 説明
github object ワークフロー実行に関する情報。
env object ワークフロー、ジョブ、ステップで設定された変数が含まれます。
vars object リポジトリ、組織、または環境レベルで設定された変数が含まれます。
job object 現在実行中のジョブに関する情報。

ヒント

コンテキストの完全な一覧については、「 コンテキストについて」を参照してください。

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

GitHub Actions には、既定の変数とコンテキストと呼ばれる 2 つの 変数 のコレクション が含まれています。 これらの変数は、ワークフロー中の様々な場所で利用されることを意図したものです。

  • 既定の環境変数: これらの環境変数は、ジョブを実行しているランナーにのみ存在します。
  • コンテキスト: 既定の変数 が使用できない場合など、ワークフロー内の任意の時点でほとんどのコンテキストを使用できます。

次の例では、 if ステートメントは、 github.ref コンテキストを調べて現在のブランチ名を確認します。 ifチェックが処理され、結果がtrue場合にのみ、ジョブがランナーに送信されます。 ジョブがランナーに送信されると、ステップが実行され、ランナーの $GITHUB_REF 変数が参照されます。

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"

GitHub Actions で使用できるコンテキスト

次の表に、使用可能な最上位レベルのコンテキスト、簡単な説明、およびオブジェクトのプロパティに関する詳細情報へのリンクを示します。

最上位レベルのコンテキスト 説明 プロパティと例
github ワークフローのあらゆるジョブやステップにおいて使用できる最上位のコンテキスト。 github コンテキストのプロパティ。
env ワークフロー、ジョブ、ステップで設定された変数が含まれます。 ランナー プロセスによって継承された変数は含まれません。 env コンテキストのプロパティ。
vars 組織、リポジトリ、および環境レベルで設定されたカスタム構成変数が含まれています。 varsの使用例。
job 現在実行中のジョブに関する情報が含まれます。 job コンテキストのプロパティ。
jobs 再利用可能なワークフローでのみ使用でき、再利用可能なワークフローの出力の設定にのみ使用できます。 jobs コンテキストのプロパティ。
steps idが指定されている現在のジョブで完了したステップに関する情報が含まれます。 steps コンテキストのプロパティ。
runner 現在のジョブを実行しているランナーに関する情報が含まれます。 runner コンテキストのプロパティ。
secrets ワークフロー実行で使用できるシークレットの名前と値が含まれます。 secrets コンテキストのプロパティ。
strategy 現在のジョブのマトリックス実行戦略に関する情報が含まれています。 strategy コンテキストのプロパティ。
matrix 現在のジョブに適用されるワークフロー ファイルで定義されているマトリックス プロパティを格納します。 matrix コンテキストのプロパティ。
needs 現在のジョブの直接依存関係として定義されているすべてのジョブからの出力が含まれます。 matrix コンテキストのプロパティ。
inputs アクション、再利用可能なワークフロー、または手動でトリガーされたワークフローに渡される入力プロパティが含まれます。 inputs コンテキストのプロパティ。

式

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

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

式を文字列として扱うのではなく、式を評価するように GitHub に指示するには、特定の構文 ( ${{ <expression> }}) を使用する必要があります。 この規則の例外は、 if 句で式を使用している場合です。通常、 ${{ および }}は省略できます。

次のコード サンプルは、環境変数の設定を示しています。

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

リテラル

式の一部としてboolean、null、number、または 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!' }}

オペレーター

演算子は、式を評価する上で重要な役割を果たします。 式は、リテラル値、コンテキストへの参照、または関数で構成できます。 演算子を使用すると、これらの要素を組み合わせて、より複雑な式を作成できます。 主な演算子を次に示します。

  • 論理演算子:

    • && (および): 2 つの条件を組み合わせ、式全体が true として評価されるようにするには、両方とも true である必要があります。
    • || (または): 2 つの条件を結合し、いずれかの条件が true の場合、式は true と評価されます。
    • ! (not): 条件を否定して、その真偽値を反転します。

  • 等値演算子:

    • == (等しい): 2 つの値が等しいかどうかを比較します。
    • != (等しくない): 2 つの値が等しくないかどうかを確認します。

  • 比較演算子:

    • < (より小さい)
    • > (より大きい)
    • <= (より小か等しい)
    • >= (以上または等しい)

これらの演算子を使用すると、条件に基づいて特定のステップを実行するタイミングを決定することで、動的ワークフローを作成できます。 適切な評価を行うには、必ず $\{\{ <expression> \}\}$などの式に正しい構文を使用してください。

演算子の詳細については、「 演算子」を参照してください。