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

完了

このユニットでは、GitHub Actions ワークフローで変数、コンテキスト、およびカスタム スクリプトを使用して、環境固有の動作を構成および管理する方法について説明します。

このプロセスを実装するには、次の方法を学習します。

• 既定の環境変数とカスタム環境変数を使用します。
• ワークフロー内のコンテキスト情報にアクセスします。
• さまざまなワークフロー スコープで環境変数を設定します。
• run キーワードでカスタム スクリプトを使用します。
• デプロイに対して環境保護を適用します。

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

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 へのデプロイの自動承認を提供できます。

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

  

注

GitHub Free、GitHub Pro、または GitHub Team プランをお持ちの場合、環境デプロイプロジェクションルールはパブリック リポジトリでのみ使用できます。分岐とタグの保護規則を除きます。 GitHub Pro または GitHub Team プランを持つユーザーの場合は、ブランチとタグの保護規則もプライベート リポジトリで使用できます。

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

上記のワークフロー スニペットの例では、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