変数の利用

GitHub Actions では、設定値や情報を「変数のように扱う」ことができます。このセクションでは、GitHub Actionsで利用できるいくつかの変数の違いや使い分けについて順番に説明します。

1. env(Environment Variables)

Environment Variables は、GitHub Actions で一般的に使われる変数の仕組みであり、env: というブロックで定義した変数をワークフローやジョブの中で利用できます。

1.1 Environment Variablesの定義

Environment Variables を定義する場合は、ワークフロー、ジョブ、ステップなど「使いたい場所」の冒頭に env: ブロックを記載します。その中に、変数名と値を記述します。

env:
  APP_NAME: demo-app
  STAGE: deployment

この例では、APP_NAME に demo-app、STAGE に deployment という値を設定しています。

Environment Variables の主な利用シーンとしては、同じワークフロー内やジョブ内で、同じ値を繰り返し利用したい場合に有効です。APP_NAME や STAGE のような値は、処理の中で複数箇所に登場することがあり、毎回直接記載すると入力誤りのリスクがあったり、値が変更になった際に修正箇所が増える可能性があります。これらの問題を防ぐために Environment Variables が役立ちます。

Environment Variables は、そのスコープ(利用範囲)に応じて定義できます。ワークフローの冒頭に記載すればワークフロー全体で利用でき、ジョブの冒頭に記載すればそのジョブ内のみ、ステップの冒頭に記載すればそのステップ内のみで利用できます。

1.2 Environment Variablesの利用方法

Environment Variables を利用したい場合は ${{ env.変数名 }} のように記載します。これにより、その部分が定義した値に展開されます。

steps:
  - name: 変数を表示
    run: echo "アプリケーション名は ${{ env.APP_NAME }}、ステージは ${{ env.STAGE }} です"

この例では、echo コマンドで APP_NAME と STAGE の値を表示しています。もちろん用途は表示に限らず、アクションのパラメータとして利用したり、変数の値に応じて処理を分岐したりするなど、幅広い活用が可能です。

2. vars(GitHub Variables)

GitHub VariablesはGitHubの画面上で定義できる設定値で、コードに直接値を記載したくない場合や、複数のワークフローで同じ値を使いたい場合などに有効です。

2.1 GitHub Variablesの定義

開発者がGitHubの画面上でGitHub Variablesを定義することで、ワークフローから使用できるようになります。設定値は変数名と値のセットで登録します。

主な利用シーンとしては、コード上に直接値を記載したくない場合や、複数のワークフローで同じ値を使いたい場合が該当します。例えば、設定値の例で挙げたAPP_NAMEやAWS_REGIONなどは、ワークフローごとに変わるものではなく、GitHub全体で共通になることが多い値です。そのため、Environment Variablesとしてワークフロー内で定義するのではなく、GitHub VariablesとしてリポジトリまたはOrganization全体に定義することが有効になります。

2.2 GitHub Variablesの設定方法

GitHub Variablesは、GitHubの設定画面から、リポジトリ単位またはOrganization単位で設定ができます。下記は、APP_NAMEとAWS_REGIONというVariablesを設定した例です。

2.3 GitHub Variablesの利用方法

Variablesを利用する場合、${{ vars.変数名 }} の形式で参照できます。

steps:
  - name: GitHub Variablesを表示
    run: echo "アプリケーション名は ${{ vars.APP_NAME }}、リージョンは ${{ vars.AWS_REGION }} です"

この形式で参照すれば、GitHubの画面上で登録した値がそのまま出力されます。

GitHub Actions の variables・secrets の使い分けや書式の詳細は、GitHub公式ドキュメントのStore information in variablesに記載があります。

3. Secrets

Secretsは、varsとは異なり、値を安全に扱うためのパラメータです。パスワードやAPIキー、認証情報など、外部に漏れてはいけない情報を扱う場合に利用します。

💡 ポイント
varsとSecretsの使い分けに迷ったら、「その値が他人に見られても問題ないか?」で判断してください。リージョン名やアプリケーション名はvarsで問題ありませんが、パスワードやAPIキーは必ずSecretsを使ってください。

3.1 Secretsの特徴

扱い方はvarsと同様にワークフローから参照できますが、GitHubに登録した時点で値は非表示となり、後から内容を確認することもできません。また、ワークフロー内で誤ってログに出力された場合でも、値は自動的にマスクされ、***のように伏せられます。この仕組みにより、安全に機密情報を扱うことができます。

設定値の例としては、PASSWORDやACCESS_KEYのような、外部に漏れてはいけない情報が対象です。

3.2 Secretsの設定方法

Secretsも、GitHubの画面上から、リポジトリ単位またはOrganization単位で設定できます。

3.3 Secretsの利用方法

Secretsを利用する場合は、事前にGitHub上で登録しておき、ワークフロー内では ${{ secrets.変数名 }} の形式で参照します。以下は、Secretsに登録したアクセスキーとパスワードを使って外部サービスにアクセスする例です。

env:
  API_URL: https://api.example-service.com

steps:
  - name: 外部サービスにデプロイ
    run: |
      curl -X POST ${{ env.API_URL }}/deploy \
        -H "X-Access-Key: ${{ secrets.ACCESS_KEY }}" \
        -H "X-Password: ${{ secrets.PASSWORD }}"

ワークフローが実行されても値そのものは表示されず、必要に応じて安全に利用されます。このように、Secretsで登録した値はGitHub内で厳重に保護される仕組みになっています。

Secretsの登録方法・スコープ(リポジトリ/環境/Organization)・暗号化の仕組みなどの詳細は、GitHub公式ドキュメントのUsing secrets in GitHub Actionsに記載があります。

4. Context

コンテキストとは、GitHub Actions が自動的に提供している変数の集合で、ワークフローがどのような状況で実行されているのかを参照するための情報です。

4.1 代表的なContext

Contextは開発者が定義する必要はなく、GitHubから自動で提供されます。

代表的なものとして、github.refで実行されたブランチの完全な参照(例:refs/heads/main)、github.ref_nameでブランチ名、github.shaでコミットを識別するID、github.actorで実行したユーザ名などが取得できます。

4.2 Contextの利用方法

Contextの利用方法ですが、コンテキスト名.プロパティ名 の形式で参照できます。

steps:
  - name: 実行情報を表示
    run: |
      echo "ブランチ名: ${{ github.ref_name }}"
      echo "コミットID: ${{ github.sha }}"
      echo "実行者: ${{ github.actor }}"

この仕組みにより、どのブランチでワークフローが動いているのか、どのコミットを対象に実行されているのか、誰が実行したのかといった内容を、実行中のワークフローから簡単に取得できます。