変数に情報を格納する

変数について

変数は、機密性の低い構成情報を格納して再利用する方法を提供します。 コンパイラ フラグ、ユーザー名、サーバー名などの任意の構成データを変数として格納できます。 変数は、ワークフローを実行するランナー マシンで補間されます。 アクションまたはワークフロー ステップ内で実行されるコマンドで、変数の作成、読み取り、変更ができます。

独自のカスタム変数を設定することも、GitHub が自動的に設定する既定の環境変数を使用することもできます。 詳しくは、「既定の環境変数」を参照してください。

カスタム変数は、2 つの方法で設定できます。

• 1 つのワークフローで使用する環境変数を定義する場合、ワークフロー ファイルで env キーを使用できます。 詳しくは、「1 つのワークフローに対する環境変数の定義」を参照してください。
• 複数のワークフローにわたって構成変数を定義する場合、Organization、リポジトリ、または環境レベルで定義できます。 詳しくは、「複数のワークフローに対する構成変数の定義」を参照してください。

単一のワークフローの環境変数の定義

単一のワークフローにカスタム環境変数を設定するには、ワークフロー ファイル内の env キーを使用して環境変数を定義できます。 このメソッドで設定されるカスタム変数のスコープは、定義されている要素に制限されます。 次のスコープを設定する変数を定義できます。

• ワークフロー全体 (ワークフロー ファイルの最上位レベルで env を使用)。
• ワークフロー内のジョブの内容 (jobs.<job_id>.env を使用)。
• ジョブ内の特定の手順 (jobs.<job_id>.steps[*].env を使用)。

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

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

env 変数の値には、ランナー環境変数またはコンテキストを使用してアクセスできます。 上の例は、echo コマンド ($DAY_OF_WEEK、$Greeting、$First_Name) でランナー環境変数として使用されている 3 つのカスタム変数を示しています。 これらの変数の値は、それぞれワークフロー、ジョブ、ステップ レベルで設定され、スコープも設定されます。 これらの変数の補間はランナーで行われます。

ワークフローの run ステップまたは参照されるアクションのコマンドは、ランナーで使用しているシェルによって処理されます。 ワークフローの一部は GitHub Actions によって処理され、ランナーには送信されません。 run ステップでは、ランナー環境変数またはコンテキストのいずれかを使用できますが、ランナーに送信されないワークフローの部分では、変数値にアクセスするためにコンテキストを使用する必要があります。 詳しくは、「構成変数の値へのアクセスにコンテキストを使用する」を参照してください。

ランナー環境変数の補間は、ワークフロー ジョブがランナー マシンに送信された後に行われるため、ランナーで使用されるシェルに適切な構文を使用する必要があります。 この例では、ワークフローは ubuntu-latest を指定します。 既定では、Linux ランナーは Bash シェルを使用するため、構文 $NAME を使用する必要があります。 既定では、Windows ランナーは PowerShell を使用するため、構文 $env:NAME を使用します。 シェルの詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

環境変数の命名規則

環境変数を設定する場合、既定の環境変数名は使用できません。 既定の環境変数の完全な一覧については、以下の「既定の環境変数」を参照してください。 これらの既定の変数のいずれかの値をオーバーライドしようとすると、割り当ては無視されます。

複数のワークフローに対する構成変数の定義

複数のワークフローにわたって使用する構成変数を作成し、Organization、リポジトリ、または環境レベルでそれらを定義できます。

たとえば、構成変数を使用して、Organization レベルでツールを構築するために渡されるパラメーターの既定値を設定しながら、リポジトリ所有者がケースバイケースでこれらのパラメーターをオーバーライドできるようにします。

構成変数を定義すると、vars コンテキストで自動的に使用できるようになります。 詳しくは、「vars コンテキストを使用した構成変数の値へのアクセス」を参照してください。

構成変数の優先順位

複数のレベルで同じ名前の変数が存在する場合、最も低いレベルの変数が優先されます。 たとえば、Organization レベルの変数名がリポジトリレベルの変数名と同じ場合、リポジトリレベルの変数が優先されます。 同様に、Organization、リポジトリ、環境がすべて同じ名前の変数を持つ場合、環境レベルの変数が優先されます。

再利用可能なワークフローの場合は、呼び出し元ワークフローのリポジトリの変数が使用されます。 呼び出されたワークフローを含むリポジトリの変数は、呼び出し元ワークフローでは使用できません。

構成変数の名前付け規則

構成変数名には次の規則が適用されます。

• 名前には英数字 ([a-z]、[A-Z]、[0-9]) またはアンダースコア (_) のみを含めることができます。 スペースは使用できません。
• 名前の最初を GITHUB_ プレフィックスにすることはできません。
• 名前の最初を数字にすることはできません。
• 名前では大文字と小文字は区別されません。
• 名前は、作成されたレベルで一意である必要があります。

リポジトリの構成変数の作成

GitHub 上で個人用アカウント リポジトリのシークレットまたは変数を作成するユーザーは、リポジトリのオーナーである必要があります。 GitHub 上で組織用リポジトリのシークレットまたは変数を作成するユーザーは、admin アクセス権を持っている必要があります。 最後に、個人用アカウント リポジトリまたは組織用リポジトリのシークレットまたは変数を REST API 経由で作成するユーザーには、コラボレーター アクセス権が必要です。

1. GitHub で、リポジトリのメイン ページに移動します。

2. リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。

   

3. サイドバーの [セキュリティ] セクションで、 [ シークレットと変数] を選択し、次に [アクション] をクリックします。

4. [変数] タブをクリックします。

   

5. [新しいリポジトリ変数] をクリックします。

6. [名前] フィールドに、変数の名前を入力します。

7. [値] フィールドに、変数の値を入力します。

8. [変数の追加] をクリックします。

環境の構成変数の作成

個人用アカウントのリポジトリ内の環境でシークレットか変数を作成するユーザーは、そのリポジトリのオーナーである必要があります。 組織用リポジトリ内の環境用にシークレットか変数を作成するユーザーには、admin のアクセス権が必要です。 環境について詳しくは、「デプロイに環境の使用」を参照してください。

1. GitHub で、リポジトリのメイン ページに移動します。

2. リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。

   

3. 左側のサイドバーで、 [環境] をクリックします。

4. 変数を追加したい環境をクリックしてください。

5. [環境変数] で [変数の追加] をクリックします。

6. [名前] フィールドに、変数の名前を入力します。

7. [値] フィールドに、変数の値を入力します。

8. [変数の追加] をクリックします。

Organization の構成変数の作成

Organization でシークレットまたは変数を作成する場合、ポリシーを使用して、リポジトリによるアクセスを制限できます。 たとえば、すべてのリポジトリにアクセスを許可したり、プライベート リポジトリまたは指定したリポジトリ のリストのみにアクセスを制限したりできます。

Organization のオーナーと、"Organization のアクション変数を管理" または "Organization のアクション シークレットを管理" のアクセス許可を持つユーザーは、Organization レベルでシークレットまたは変数を作成できます。

詳しくは、「カスタム組織の役割の情報」をご覧ください。

1. GitHub で、organization のメイン ページに移動します。

2. 組織名の下で、 [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。

   

3. サイドバーの [セキュリティ] セクションで、 [ シークレットと変数] を選択し、次に [アクション] をクリックします。

4. [変数] タブをクリックします。

   

   注: アクセス許可によっては、[アクション シークレットと変数] ページにシークレットと変数の個別タブが表示されない場合があります。 "Organization のアクション変数を管理" と "Organization のアクション シークレットを管理" アクセス許可の両方を持つ Organization の所有者とユーザーには、[変数] と [シークレット] タブが表示されます。 詳しくは、「カスタム組織の役割の情報」を参照してください。

5. [新しい Organization 変数] をクリックします。

6. [名前] フィールドに、変数の名前を入力します。

7. [値] フィールドに、変数の値を入力します。

8. [リポジトリアクセス] ドロップダウンリストから、アクセスポリシーを選びます。

9. [変数の追加] をクリックします。

構成変数の制限

個々の変数のサイズは最大 48 KB です。

最大で 1,000 個の組織変数、リポジトリあたり 500 個の変数、および環境あたり 100 個の変数を格納できます。 組織変数とリポジトリ変数の合計サイズの上限は、ワークフローの実行あたり 10 MB です。

リポジトリに作成されたワークフローは、次の数の変数にアクセスできます。

• リポジトリ変数の合計サイズが 10 MB 未満の場合、リポジトリ変数は最大 500 個です。 リポジトリ変数の合計サイズが 10 MB を超える場合、(変数名でアルファベット順に並べ替えをして) 制限を超えないリポジトリ変数のみが使用できます。
• リポジトリ変数と組織変数の合計サイズが 10 MB 未満の場合、組織変数は最大 1,000 個です。 組織変数とリポジトリ変数の合計サイズが 10 MB を超える場合は、(リポジトリ変数を処理した後、変数名でアルファベット順に並べ替えをして) その制限を超えない組織変数のみが使用できます。
• 最大 100 個の環境レベル変数。

コンテキストを使用した変数の値へのアクセス

コンテキストは、ワークフローの実行、変数、ランナーの環境、ジョブ、ステップに関する情報にアクセスする方法です。詳細については、「ワークフロー実行に関するコンテキスト情報へのアクセス」を参照してください。 ワークフローには、さまざまな目的で使用できる他の多くのコンテキストがあります。 ワークフロー内で特定のコンテキストを使用できる場所の詳細については、「ワークフロー実行に関するコンテキスト情報へのアクセス」を参照してください。

env コンテキストを使用して環境変数値にアクセスし、vars コンテキストを使用して構成変数値にアクセスできます。

env コンテキストを使用した環境変数の値へのアクセス

GitHub Actions では、ランナー環境変数に加えて、コンテキストを使用した env キー値の設定および読み取りを行うことができます。 環境変数やコンテキストは、ワークフロー中の様々な場所で利用できます。

ワークフローまたは参照先アクションの run ステップは、ランナーによって処理されます。 その結果、ランナーで使用するシェル (Linux ランナーの bash シェル用の $NAME や Windows ランナーの PowerShell用の $env:NAME など) に適した構文を使用して、ランナー環境変数をここで使用できます。 ほとんどの場合、コンテキストと構文 ${{ CONTEXT.PROPERTY }} を使用して、同じ値にアクセスすることもできます。 違いは、ジョブがランナーに送信される前にコンテキストが補間され、文字列に置き換えられるということです。

ただし、GitHub Actions によって処理され、ランナーには送信されないワークフローの一部のランナー環境変数値は使用できません。 その代わりに、コンテキストを使用することができます。 たとえば、ジョブまたはステップがランナーに送信されるかどうかを決定する if 条件は、常に GitHub Actions によって処理されます。 if 条件付きステートメントでコンテキストを使用して、変数の値にアクセスする必要があります。

name: Conditional env variable

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"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

name: Conditional env variable

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"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

前の例のこの変更では、if 条件を導入しました。 ワークフロー ステップは、DAY_OF_WEEK が "Monday" に設定されている場合にのみ実行されます。 env コンテキストを使用して、if 条件付きステートメントからこの値にアクセスします。 run コマンド内で参照される変数には、 env コンテキストは必要ありません。 これらはランナー環境変数として参照され、ランナーがジョブを受信した後に補間されます。 ただし、コンテキストを使用して、ランナーにジョブを送信する前に、これらの変数を補間することを選択できました。 結果の出力は同じになります。

run: echo "${{ env.Greeting }} ${{ env.First_Name }}. Today is ${{ env.DAY_OF_WEEK }}!"

ジョブがランナーに送信される前に処理されるワークフローの一部で、変数の値にアクセスするには、通常 env または github コンテキストを使用します。

vars コンテキストを使用した構成変数の値へのアクセス

構成変数には、vars コンテキストを使用してワークフロー全体でアクセスできます。 詳細については、「ワークフロー実行に関するコンテキスト情報へのアクセス」を参照してください。

構成変数が設定されていない場合、変数を参照するコンテキストの戻り値は空の文字列になります。

次の例は、ワークフロー全体で vars コンテキストと共に構成変数を使用する方法を示しています。 次の各構成変数は、リポジトリ、Organization、または環境レベルで定義されています。

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

既定の環境変数

GitHub が設定する既定の環境変数は、ワークフローのどのステップでも使用できます。

既定の環境変数は GitHub によって設定され、ワークフローで定義されていないため、env コンテキストを介してアクセスすることはできません。 しかし、既定の変数のほとんどは、対応する、似た名前のコンテキスト プロパティを持ちます。 たとえば、${{ github.ref }} コンテキスト プロパティを使用してワークフロー処理中に GITHUB_REF 変数の値を読み取ることができます。

GITHUB_* および RUNNER_* という名前の既定の環境変数の値を上書きすることはできません。 現時点では、CI 変数の値を上書きできます。 ただし、これが常に可能になることは保証されていません。 環境変数の設定の詳細については、「1 つのワークフローの環境変数の定義」および「GitHub Actions のワークフロー コマンド」を参照してください。

アクションでは、ファイルシステムにアクセスするとき、ハードコードされたファイル パスを使うのではなく変数を使用することを強くお勧めします。 GitHub は、すべてのランナー環境でアクションが使用する変数を設定します。

オペレーティング システムの検出

既定の環境変数 RUNNER_OS と対応するコンテキスト プロパティ ${{ runner.os }} を使用して、異なるオペレーティング システムに使用できる 1 つのワークフロー ファイルを記述できます。 たとえば、ランナーによって使用されるシェルに応じて異なる、環境変数の構文を変更しなくても、オペレーティング システムを macos-latest から windows-latest に変更した場合、次のワークフローを正常に実行できます。

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."

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."

この例では、2 つの if ステートメントによって runner コンテキストの os プロパティがチェックされ、ランナーのオペレーティング システムが決定されます。 if 条件は GitHub Actions によって処理され、チェックによって true として解決されるステップのみ、ランナーに送信されます。 ここでは、チェックの 1 つが常に true となり、もう 1 つが false になるため、これらのステップの 1 つだけがランナーに送信されます。 ジョブがランナーに送信されると、ステップが実行され、echo コマンド内の環境変数が適切な構文を使用して補間されます (Windows の PowerShell の場合 $env:NAME、Linux および macOS の bash と sh の場合 $NAME)。 この例では、ステートメント runs-on: macos-latest では 2 番目のステップが実行されます。

ワークフロー内のステップとジョブの間で値を渡す

ジョブの 1 つのステップで値を生成する場合は、既存または新しい環境変数に値を割り当て、これを GITHUB_ENV 環境ファイルに書き込むことで、同じジョブの後続のステップで値を使用できます。 環境ファイルは、アクションによって直接使用することも、run キーワードを使用してワークフロー ファイル内のシェル コマンドから使用することもできます。 詳しくは、「GitHub Actions のワークフロー コマンド」を参照してください。

ワークフロー内のあるジョブのステップから、そのワークフロー内の別のジョブのステップに値を渡す場合は、その値をジョブ出力として定義できます。 その後、別のジョブのステップからこのジョブ出力を参照できます。 詳しくは、「GitHub Actions　のワークフロー構文」を参照してください。