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

12 分

ここでは、既定およびカスタムの環境変数、カスタムスクリプト、キャッシュ依存関係を使用して、ジョブ間で成果物データを渡す方法について説明します。また、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 の場合は、ランナーが実行され、"ブランチ $GITHUB _REF の実稼働サーバーにデプロイしています" と出力されます。既定の環境変数 $GITHUB_REF は、ランナーでブランチを参照するために使用されます。既定の環境変数はすべて大文字で、コンテキスト変数はすべて小文字であることに注意してください。

カスタム環境変数

既定の環境変数を使用する場合と同様に、ワークフローファイルでカスタム環境変数を使用できます。カスタム変数を作成するには、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

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

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

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

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

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

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

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

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

パラメーター	Description	必要
キー	キャッシュを保存および検索するときに作成されるキー識別子を参照します。	はい
パス	キャッシュまたは検索するランナー上のファイルパスを参照します。	はい
復元キー	目的のキャッシュキーが見つからない場合は、キャッシュに対する別の既存のキーで構成されます。	いいえ

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 ハッシュが含まれています。 restore-keys フォールバックを使用し、複数のキャッシュがある場合、キーのプレフィックスを ID (この例では npm-cache) にすると便利です。

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

ワークフロー内の依存関係をキャッシュするという考え方と同様に、同じワークフロー内のジョブ間でデータを渡すことができます。これを行うには、upload-artifact と download-artifact のアクションを使います。前のジョブの成果物に依存しているジョブの実行は、前のジョブが正常に完了するまで待機する必要があります。これは、前のジョブからアップロードされた成果物に基づいて順番に実行する必要がある一連のジョブがある場合に便利です。たとえば、job_2 では needs: job_1 構文を使用することにより 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 では、needs: job_1 構文を使用して job_1 を完了する必要があります。その後、actions/download-artifact@v2 アクションを使用してその成果物をダウンロードし、file.txt の内容を印刷します。

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

場合によっては、既定のワークフローログでは、特定のワークフローの実行、ジョブ、またはステップが失敗した原因を診断するのに十分な詳細情報が提供されません。このような状況では、"実行" と "ステップ" の 2 つのオプションについて、追加のデバッグログを有効にすることができます。この診断ログ記録を有効にするには、リポジトリへの admin アクセスを必要とする 2 つのリポジトリシークレットを true に設定します。

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

ユーザーインターフェイスからワークフローログにアクセスする

自動化の成功を考える際、重要な内容に焦点を絞ることができるよう、自動化されていることを確認するための時間を最小限に抑えることを目指します。しかし、場合によっては計画どおりに物事が進まないことがあり、何が起こったかを確認する必要があります。そのようなデバッグプロセスは面倒な場合があります。ただし、GitHub には、現在のデバッグ手順のコンテキストを維持しながら、ジョブ間をすばやく移動できるようにする、明確なレイアウト構造が用意されています。 GitHub で実行されるワークフローのログを表示するには、次の手順に従います。

リポジトリの [アクション] タブに移動します。
左側のサイドバーで、目的のワークフローをクリックします。
ワークフロー実行のリストから、目的の実行を選択します。
[ジョブ] で、目的のジョブを選択します。
ログ出力を読みます。

ワークフロー内で複数の実行がある場合は、ワークフローを選択した後に [ステータス] フィルターを選択し、[失敗] に設定することにより、そのワークフロー内で失敗した実行のみを表示することもできます。

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

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

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

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

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

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

カスタム環境変数

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

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

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

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

ユーザー インターフェイスからワークフロー ログにアクセスする

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

フィードバック

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

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

ユーザーインターフェイスからワークフローログにアクセスする

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