環境変数と成果物データを使用してワークフローをカスタマイズする

このユニットでは、既定の環境変数とカスタム環境変数を使用する方法、カスタム スクリプトを使用する方法、依存関係をキャッシュする方法、ジョブ間で成果物データを渡す方法について説明します。 また、GitHub Web サイトと REST API エンドポイントの両方からワークフロー ログにアクセスする方法についても説明します。

既定の環境変数とコンテキスト

GitHub Actions ワークフロー内では、いくつかの既定の環境変数を使用できますが、ジョブを実行しているランナー内でのみ使用できます。 これらの既定の変数は大文字と小文字が区別され、システムと現在のユーザーの構成値を参照します。 ハードコーディングされたファイル パスを使用するのではなく、これらの既定の環境変数を使用してファイル システムを参照することをお勧めします。 既定の環境変数を使用するには、$ の後に環境変数の名前を指定します。

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

既定の環境変数に加えて、定義された変数をコンテキストとして使用できます。 コンテキストと既定の変数は、両方とも環境情報へのアクセスを提供するという点で似ていますが、いくつかの重要な違いがあります。 既定の環境変数はランナー内でのみ使用できますが、ワークフロー内の任意の時点でコンテキスト変数を使用できます。 たとえば、コンテキスト変数を使用すると、if ステートメントを実行して、ランナーが実行される前に式を評価できます。

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.ref コンテキストを使用して、ワークフローをトリガーしたブランチを確認します。 ブランチが mainされている場合、ランナーが実行され、"Deploying to production server on branch $GITHUB_REF" が出力されます。ランナーで $GITHUB_REF 既定の環境変数がブランチを参照するために使用されます。 既定の環境変数はすべて大文字で、コンテキスト変数はすべて小文字であることに注意してください。

ワークフローで利用可能なコンテキスト情報

コンテキストを使用して、ワークフローの実行、変数、ランナー環境、ジョブ、ステップに関する情報にアクセスします。 各コンテキストは、他のオブジェクトまたは文字列にすることができるプロパティを含むオブジェクトです。 使用できるコンテキストには、 github、 env、 vars、 job、 jobs、 steps、 runner、 secrets、 strategy、 matrix、 needs、 inputsなどがあります。

次の表に、ワークフローのコンテキストと説明を示します。

コンテキスト	説明
github	ワークフロー実行に関する情報。 詳しくは、「github コンテキスト」を参照してください。
env	ワークフロー、ジョブ、またはステップで設定した変数が含まれます。 詳しくは、「env コンテキスト」を参照してください。
vars	リポジトリ、組織、または環境レベルで設定した変数が含まれます。 詳しくは、「vars コンテキスト」を参照してください。
job	現在実行中のジョブに関する情報。 詳しくは、「job コンテキスト」を参照してください。
jobs	再利用可能なワークフローの場合のみ、再利用可能なワークフローからのジョブの出力が含まれます。 詳しくは、「jobs コンテキスト」を参照してください。
steps	現在のジョブで実行されたステップに関する情報。 詳しくは、「steps コンテキスト」を参照してください。
runner	現在のジョブを実行しているランナーに関する情報。 詳しくは、「runner コンテキスト」を参照してください。
secrets	ワークフロー実行で使用できるシークレットの名前と値が含まれます。 詳しくは、「secrets コンテキスト」を参照してください。
strategy	現在のジョブのマトリックス実行戦略に関する情報。 詳しくは、「strategy コンテキスト」を参照してください。
matrix	現在のジョブに適用されるワークフローで定義されているマトリックス プロパティが含まれます。 詳しくは、「matrix コンテキスト」を参照してください。
needs	現在のジョブの依存関係として定義されているすべてのジョブの出力が含まれます。 詳しくは、「needs コンテキスト」を参照してください。
inputs	再利用可能な、または手動で行ったワークフローの入力が含まれます。 詳しくは、「inputs コンテキスト」を参照してください。

ワークフロー実行では、異なるコンテキストが異なる時間に使用できます。 たとえば、 secrets コンテキストはジョブ内の特定の場所でのみ使用できます。 また、 hashFiles 関数などの一部の関数は、特定の場所でのみ使用できます。

次の表に、ワークフロー内の各コンテキストと特殊な関数の制限を示します。 一覧表示されているコンテキストは、指定されたワークフロー キーに対してのみ使用できます。 他の場所では使用できません。 次の表に示す場合を除き、任意の場所で関数を使用できます。

ワークフロー キー	コンテキスト	特殊な関数
run-name	github、 inputs、 vars	無し
concurrency	github、 inputs、 vars	無し
env	github、 secrets、 inputs、 vars	無し
jobs.<job_id>.concurrency	github、 needs、 strategy、 matrix、 inputs、 vars	無し
jobs.<job_id>.container	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.container.credentials	github、 needs、 strategy、 matrix、 env、 vars、 secrets、 inputs	無し
jobs.<job_id>.container.env.<env_id>	github、needs、strategy、matrix、job、runner、env、vars、secrets、inputs	無し
jobs.<job_id>.container.image	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.continue-on-error	github、 needs、 strategy、 vars、 matrix、 inputs	無し
jobs.<job_id>.defaults.run	github､needs、strategy、matrix、env、vars、inputs	無し
jobs.<job_id>.env	github､needs、strategy、matrix、vars、secrets、inputs	無し
jobs.<job_id>.environment	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.environment.url	github、needs、strategy、matrix、job、runner、env、vars、steps、inputs	無し
jobs.<job_id>.if	github、 needs、 vars、 inputs	always、 canceled、 success、 failure
jobs.<job_id>.name	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.outputs.<output_id>	github、 needs、 strategy、 matrix、 job、 runner、 env、 vars、 secrets、 steps、 inputs	無し
jobs.<job_id>.runs-on	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.secrets.<secrets_id>	github､needs、strategy、matrix、secrets、inputs、vars	無し
jobs.<job_id>.services	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.services.<service_id>.credentials	github、 needs、 strategy、 matrix、 env、 vars、 secrets、 inputs	無し
jobs.<job_id>.services.<service_id>.env.<env_id>	github、needs、strategy、matrix、job、runner、env、vars、secrets、inputs	無し
jobs.<job_id>.steps.continue-on-error	github、 needs、 strategy、 matrix、 job、 runner、 env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.steps.env	github、 needs、 strategy、 matrix、 job、 runner、 env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.steps.if	github、needs、strategy、matrix、job、runner、env、vars、steps、inputs	always、 canceled、 success、 failure、 hashFiles
jobs.<job_id>.steps.name	github、 needs、 strategy、 matrix、 job、 runner、 env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.steps.run	github、 needs、 strategy、 matrix、 job、 runner、 env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.steps.timeout-minutes	github、 needs、 strategy、 matrix、 job、 runner、 env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.steps.with	github、 needs、 strategy、 matrix、 job、 runner、env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.steps.working-directory	github、 needs、 strategy、 matrix、 job、 runner、env、 vars、 secrets、 steps、 inputs	hashFiles
jobs.<job_id>.strategy	github、needs、vars、inputs	無し
jobs.<job_id>.timeout-minutes	github、 needs、 strategy、 matrix、 vars、 inputs	無し
jobs.<job_id>.with.<with_id>	github、 needs、 strategy、 matrix、 inputs、 vars	無し
on.workflow_call.inputs.<inputs_id>.default	github、 inputs、 vars	無し
on.workflow_call.outputs.<output_id>.value	github、jobs、vars、inputs	無し

カスタム環境変数

既定の環境変数を使用する場合と同様に、ワークフロー ファイルでカスタム環境変数を使用できます。 カスタム変数を作成するには、env コンテキストを使用してワークフロー ファイルで定義する必要があります。 ランナー内で環境変数の値を使用する場合は、環境変数を読み取るためのランナー オペレーティング システムの通常のメソッドを使用できます。

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

ワークフローでカスタム環境変数を設定する

ワークフロー ファイルの最上位レベルで env を使用して、ワークフロー全体を対象とする環境変数を定義できます。 jobs.<job_id>.envを使用して、ワークフロー内のジョブの内容のスコープを設定します。 jobs.<job_id>.steps[*].envを使用して、ジョブ内の特定のステップで環境変数のスコープを設定できます。

ワークフロー ファイル内の 3 つのシナリオすべてを示す例を次に示します。

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

ワークフローで既定のコンテキストを使用する

GitHub プラットフォームでは、既定の環境変数が設定されます。 これらはワークフローで定義されていませんが、ワークフロー内の適切なコンテキストで既定の環境変数を使用できます。 これらの変数のほとんどは、 CIを除き、 GITHUB_* または RUNNER_*で始まります。 後者の 2 つの型は上書きできません。 また、これらの既定の変数には、対応する同様の名前付きコンテキスト プロパティがあります。 たとえば、 RUNNER_* 一連の既定の変数には、 runner.*の一致するコンテキスト プロパティがあります。

次のメソッドを適用して、ワークフロー内の既定の変数にアクセスする方法の例を次に示します。

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

詳しくは、「既定の環境変数」をご覧ください。

カスタム環境変数をワークフローに渡す

ワークフロー ジョブの 1 つのステップからジョブ内の後続のステップにカスタム環境変数を渡すことができます。 ジョブの 1 つのステップで値を生成し、その値を既存または新しい環境変数に割り当てます。 次に、変数と値のペアをGITHUB_ENV環境ファイルに書き込みます。 run キーワードを使用して、アクションまたはワークフロー ジョブのシェル コマンドから環境ファイルを使用できます。

環境変数を作成または更新するステップは新しい値にアクセスできませんが、ジョブ内の後続のすべてのステップにアクセスできます。

次に例を示します。

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

環境保護を追加する

GitHub リポジトリに対して定義されている環境の保護規則を追加できます。

環境を追加するには、リポジトリに次の手順を実行します。

1. 設定を選択します。

   

2. 左側のウィンドウで、[ 環境] を選択します。

   

3. [ 新しい環境 ] ボタンを選択して、環境を追加して構成し、保護を追加します。

   

環境について

環境を使用して、運用、ステージング、開発などの一般的なデプロイ ターゲットを記述します。 GitHub Actions ワークフローが環境にデプロイされると、その環境がリポジトリのメイン ページに表示されます。 環境を使用して、ジョブの続行の承認を要求したり、ワークフローをトリガーできるブランチを制限したり、カスタムデプロイ保護ルールを使用してデプロイをゲートしたり、シークレットへのアクセスを制限したりできます。

ワークフロー内の各ジョブは、1 つの環境を参照できます。 環境を参照するジョブがランナーに送信される前に、その環境に対して設定した保護ルールに合格することが必要です。 ジョブがランナーに送信された後でのみ、ジョブは環境のシークレットにアクセスできます。

ワークフローが環境を参照すると、その環境がリポジトリのデプロイに表示されます。

環境保護ルール

環境デプロイ保護規則では、環境を参照するジョブを続行する前に、特定の条件に合格する必要があります。 デプロイ保護規則を使用して、手動承認の要求、ジョブの遅延、特定のブランチへの環境の制限を行うことができます。 GitHub Apps を利用してカスタム保護規則を作成して実装し、パートナー システムを使用して、GitHub で構成されている環境を参照するデプロイを制御することもできます。

これらの保護規則の説明を次に示します。

• 必須の校閲者保護規則。 環境を参照するワークフロー ジョブの承認を特定のユーザーまたはチームに要求するには、このルールを使用します。 レビュー担当者とすることができるユーザーまたはチームの最大数は 6 です。 レビュー担当者には、少なくともリポジトリに対する読み取りアクセス許可が必要です。 続行するには、1 人の必須レビュー担当者だけがジョブを承認する必要があります。

  また、保護された環境へのデプロイの自己レビューを防ぐこともできます。 この設定を有効にした場合、展開を開始するユーザーは、必要なレビュー担当者であっても、展開ジョブを承認できません。 自己レビューを有効にすると、保護された環境へのデプロイを複数のユーザーが確認できるようになります。

  必須レビュー担当者が含まれる環境を参照するジョブのレビューについて詳しくは、「デプロイメントのレビュー」を参照してください。

• 待機タイマーのプロジェクションルール。 待機タイマー保護規則を使用すると、環境のデプロイが進む前にジョブが最初にトリガーされた後、ジョブを特定の時間遅延させることができます。 時間 (分単位) は、1 から 43,200 (30 日) の間の整数である必要があります。 待機時間は課金対象の時間にはカウントされません。

• ブランチとタグの保護規則。 デプロイ ブランチとタグ保護規則を使用して、環境へのデプロイに使用するブランチとタグを制限できます。 環境の展開ブランチとタグ保護規則には、いくつかのオプションがあります。

  • どの ブランチまたはタグを環境にデプロイできるかに関する制限は設定されません。
  • 保護されたブランチでは、 環境へのデプロイが有効になっているブランチ保護規則を持つブランチのみが許可されます。 リポジトリ内のどのブランチにもブランチ保護ルールが定義されていない場合は、すべてのブランチをデプロイできます。 [選択したブランチとタグ] 設定では、指定した名前パターンに一致するブランチとタグのみが環境にデプロイできます。
  • 展開ブランチまたはタグルールとして releases/* を指定した場合、 releases/ で始まる名前のブランチまたはタグのみを環境にデプロイできます。 (ワイルドカード文字が /と一致しません。 release/ で始まり、別のスラッシュを含むブランチまたはタグを照合するには、 release/*/*を使用します)。 main をブランチ ルールとして追加すると、 main という名前のブランチを環境にデプロイすることもできます。

• カスタム展開保護規則。 カスタム保護規則を作成して、パートナー サービスを使用するようにデプロイを制限できます。 たとえば、可観測性システム、変更管理システム、コード品質システム、またはその他の手動構成を使用して、準備状況を評価し、GitHub へのデプロイの自動承認を提供できます。

  カスタムデプロイ保護規則を作成してリポジトリにインストールした後、リポジトリ内の任意の環境に対してカスタムデプロイ保護規則を有効にすることができます。

  

ワークフロー内のスクリプト

上記のワークフロー スニペットの例では、run キーワードを使用してテキストの文字列を出力しています。 run キーワードから、ランナーでコマンドを実行するようにジョブへの指示が出るので、run キーワードを使用してアクションまたはスクリプトを実行します。

jobs:
  example-job:
    steps:
      - run: npm install -g bats

この例では、npm を使用して、bats キーワードを使用してrun ソフトウェア テスト パッケージをインストールします。 また、スクリプトをアクションとして実行することもできます。 スクリプトをリポジトリに格納し (多くの場合 .github/scripts/ ディレクトリで実行)、run キーワードを使用してパスとシェルの種類を指定できます。

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

キャッシュ アクションを使用して依存関係をキャッシュする

ワークフローを構築するときは、多くの場合、同じ出力を再利用するか、ある実行から別の実行に依存関係をダウンロードする必要があります。 これらの依存関係を繰り返しダウンロードするのではなく、それらをキャッシュして、ワークフローの実行速度と効率を向上させることができます。 GitHub でホストされるランナー上のジョブは毎回クリーンな仮想環境で開始されるため、依存関係をキャッシュすると、ワークフローで特定の手順を実行するのにかかる時間が短縮されます。

ジョブの依存関係をキャッシュするには、GitHub の cache アクションを使用します。 このアクションでは、指定した一意のキーによって識別されるキャッシュを取得します。 アクションによってキャッシュが検出されると、構成したパスにキャッシュされたファイルが取得されます。 cache アクションを使用するには、いくつかの特定のパラメーターを設定する必要があります。

パラメーター	説明	必須
Key	キャッシュを保存および検索するときに作成されるキー識別子を参照します。	はい
Path	キャッシュまたは検索するランナー上のファイル パスを参照します。	はい
Restore-keys	目的のキャッシュ キーが見つからない場合にキャッシュする代替の既存のキーで構成されます。	いいえ

steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

上の例では、path は ~/.npm に設定され、key にはランナーのオペレーティング システムと package-lock.json ファイルの SHA-256 ハッシュが含まれています。 npm-cache フォールバックを使用し、複数のキャッシュがある場合、キーのプレフィックスを ID (この例では restore-keys) にすると便利です。

ジョブ間で成果物データを渡す

ワークフロー内で依存関係をキャッシュするという考え方と同様に、同じワークフロー内のジョブ間でデータを渡すことができます。 upload-artifactアクションとdownload-artifactアクションを使用して、データを渡すことができます。 前のジョブの成果物に依存しているジョブの実行は、前のジョブが正常に完了するまで待機する必要があります。 この方法は、以前のジョブからアップロードされた成果物に基づいて順番に実行する必要がある一連のジョブがある場合に便利です。 たとえば、job_2 では job_1 構文を使用することにより needs: job_1 が必要となっています。

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

この例には 2 つのジョブがあります。 job_1 は、 file.txt ファイルにテキストを書き込みます。 その後、actions/upload-artifact@v2 アクションを使用してこの成果物をアップロードし、後でワークフロー内で使用できるようにデータを保存します。 job_2 は、job_1 に needs: job_1 構文を使用して完了することを要求します。 その後、actions/download-artifact@v2 アクションを使用してその成果物をダウンロードし、file.txt の内容を出力します。

ワークフローでステップ デバッグ ログを有効にする

場合によっては、既定のワークフロー ログでは、特定のワークフローの実行、ジョブ、またはステップが失敗した理由を診断するのに十分な詳細が提供されない場合があります。 これらのシナリオでは、 実行 と ステップの 2 つのオプションに対して、より多くのデバッグ ログを有効にすることができます。 リポジトリへの admin アクセスを必要とする 2 つのリポジトリ シークレットを trueに設定して、この診断ログを有効にします。

• 診断ログの実行を有効にするには、ワークフローを含むリポジトリの ACTIONS_RUNNER_DEBUG シークレットを trueに設定します。
• ステップ診断ログを有効にするには、ワークフローを含むリポジトリの ACTIONS_STEP_DEBUG シークレットを true に設定します。

GitHub でワークフロー ログにアクセスする

自動化の成功を考える場合は、関連性に集中できるように、自動化された内容を見るために最小限の時間を費やすことを目指します。 しかし、状況が計画どおりに進まない場合があり、何が起こったかを確認する必要があります。 そのようなデバッグ プロセスは面倒な場合があります。

GitHub には、現在のデバッグ 手順のコンテキストを保持しながらジョブ間をすばやく移動するのに役立つ、明確で構造化されたレイアウトがあります。

GitHub でワークフロー実行のログを表示するには:

1. リポジトリで、[ アクション] タブに移動します。
2. 左側のウィンドウで、ワークフローを選択します。
3. ワークフロー実行の一覧で、実行を選択します。
4. ジョブ の下で、ジョブを選択します。
5. ログ出力を読みます。

ワークフロー内に複数の実行がある場合は、ワークフローを選択し、[失敗] に設定した後で [状態] フィルターを選択すると、そのワークフローで失敗した実行のみが表示されます。

REST API からワークフロー ログにアクセスする

GitHub を使用してログを表示するだけでなく、GitHub REST API を使用してワークフロー実行のログを表示したり、ワークフローを再実行したり、ワークフローの実行をキャンセルしたりできます。 API を使用してワークフロー実行のログを表示するには、ログ エンドポイントに GET 要求を送信します。 リポジトリに対する読み取りアクセス権を持つすべてのユーザーがこのエンドポイントを使用できることに注意してください。 リポジトリがプライベートである場合は、repo スコープでアクセス トークンを使用する必要があります。

たとえば、特定のワークフロー実行ログを表示する GET 要求は、次のパスに従います。

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs

GitHub アプリからインストール トークンを使用するタイミングを特定する

GitHub アプリがアカウントにインストールされている場合は、REST および GraphQL API 要求の installation access token を使用して、アプリのインストールとして認証できます。 この手順では、アプリに必要なリポジトリのアクセスとアクセス許可が付与されていると仮定して、アプリがインストールによって所有されているリソースにアクセスできるようにします。 アプリのインストールによって行われた REST または GraphQL API 要求は、アプリに起因します。

次の例では、 INSTALLATION_ACCESS_TOKEN をインストール アクセス トークンに置き換えます。

curl --request GET \
--url "https://api.github.com/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

インストール アクセス トークンを使って、HTTP ベースの Git アクセスの認証を行うこともできます。 アプリには、 Contents リポジトリのアクセス許可が必要です。 その後は、インストール アクセス トークンを HTTP パスワードとして使用できます。

この例の TOKEN は、インストール アクセス トークンに置き換えます。

git clone https://x-access-token:TOKEN@github.com/owner/repo.git