GitHub Actionsの環境変数の使い方

著者

Lewis Gavin

2022年11月22日

0 分で読めます

How to Use GitHub Actions Environment Variables and Secrets

動作するコードを本番環境へ効率よくリリースするには、継続的インテグレーション／継続的デリバリー（CI/CD）パイプラインを導入するのが効果的です。こうしたパイプラインは、コード変更がリリース可能かどうかを確認するプロセスを自動化し、本番環境へのリリースを自動化するツールを提供します。

その一般的な方法の一つが、既存のバージョン管理システムを利用することです。GitHubは広く使われているバージョン管理システムの一つで、開発者がコードのビルド、テスト、デプロイを自動化できるGitHub Actionsを提供しています。これにより、安全なCI/CDパイプラインの構築が可能になります。

GitHub Actionsのジョブでは、環境変数へのアクセスが必要になることがよくあります。環境変数はあらかじめ定義でき、特定の環境で実行されるパイプラインからのみアクセスできます。これにより、環境変数に応じてCI/CDパイプラインの動作を変更できます。たとえば、本番環境へのデプロイ前に、アプリケーションの最適化された本番用バージョンをビルドするよう切り替えられます。

この記事では、GitHub Actionsで利用できる環境変数と、その使いどころを実践的に解説します。

前提条件

このチュートリアルを進めるには、次のものが必要です。

コードエディターを使用できる環境（このチュートリアルではVisual Studio Codeを使用）と、GitHubアカウント。
サンプルコード。環境変数の動作を説明するために使用する、シンプルなJavaアプリケーションが含まれています。

開発中にプロジェクトをスキャンできるVisual Studio Code用のSnykプラグインをご存じですか？詳しくはドキュメントをご覧ください。

GitHub Actionsの環境変数でできること

サンプルコードをダウンロードしたら、GitHubで新しいリポジトリを作成し、サンプルコードを追加します。

サンプルコードには、GitHub Actionsのワークフローファイルの例がすでに含まれています。以下のコードは、ファイル.github/workflows/pipeline.ymlの内容です。

1name: Java CI with Maven
2
3on:
4  push:
5    branches: [ "main" ]
6  pull_request:
7    branches: [ "main" ]
8
9jobs:
10  build:
11
12    runs-on: ubuntu-latest
13
14    steps:
15    - uses: actions/checkout@v3
16    - name: Set up JDK 21
17      uses: actions/setup-java@v3
18      with:
19        java-version: '21'
20        distribution: 'temurin'
21        cache: maven
22    - name: Build with Maven
23      run: mvn -B package --file pom.xml

このファイルでは、Mavenを使ってJavaアプリケーションをビルドするシンプルなワークフローを定義しています。

ワークフローのYAML設定ファイルでは、ワークフロー、ジョブ、ステップの3つのレベルで環境変数を定義できます。これらのレベルによって、環境変数の適用範囲が決まります。ワークフローレベルの環境変数はワークフロー全体に適用されます。ジョブレベルの環境変数は特定のジョブに適用されます。ステップレベルの環境変数は特定のステップに適用されます。

それぞれの環境変数を詳しく見ていきましょう。

ワークフローレベルの環境変数

ワークフローレベルの環境変数を設定するには、YAMLファイルの最上位で定義します。ファイル上部のNAME変数の下に、次の内容を追加しましょう。

1env:
2  NAME: 'Snyk Demo'

このコードでは、NAMEという環境変数を定義しています。この変数は、ワークフロー内のどこからでも参照できます。変数にアクセスするには、UNIXの環境変数と同様の専用構文を使います。NAME変数を使うには、先頭にドル記号を付けて$NAMEとします。

23行目に、この変数を出力する新しいステップを追加しましょう。

1- name: Print name
2  run: echo "Hello $NAME"

この変更をコミットし、リポジトリにプッシュします。

次に、ブラウザーでGitHubを開き、リポジトリのActionsタブに移動します。Jobsの下にある最新のワークフローを選択し、ビルドジョブの出力を開きます。Print nameをクリックします。展開すると、下の画像のように環境変数が正しく出力されていることを確認できます。

GitHub Actionsのビルドログ。ワークフローの成功と、NAME変数から「Hello Snyk Demo」を出力するPrint nameステップを表示。

ワークフローレベルの環境変数は、すべてのジョブとステップに適用する変数の宣言に便利です。たとえば、ワークフローが実行される環境を開発、テスト、本番のいずれかに設定できます。npmでビルドするNode.jsアプリケーションでは、NODE_ENV変数を利用できるため、特に便利です。この変数を使うと、各ジョブが環境に応じて適切に動作します。npmパッケージを安全に公開する方法については、Snykブログのこちらの記事をご覧ください。

ジョブレベルの環境変数

次に、ジョブとステップの環境変数を設定する方法を見てみましょう。ワークフローレベルの環境変数と同じ方法で設定できますが、該当するセクション内で定義します。

ジョブの変数として、Javaのバージョンを次のように定義します。

1jobs:
build:
  env:
      JAVA_VERSION: '21'

これで、各ステップ内で前述と同じようにこの変数を使えます。

1steps:
2- uses: actions/checkout@v3
3- name: Set up JDK ${{env.JAVA_VERSION}}
4  uses: actions/setup-java@v3
5  with:
6    java-version: ${{env.JAVA_VERSION}}
7    distribution: 'temurin'
8    cache: maven

ただし、JAVA_VERSION環境変数を使うときは、構文が少し異なることに気づくでしょう。これはコンテキストを使って環境変数にアクセスする例です。コンテキストを使うと、GitHub Actionsはどの仮想マシン上でも環境変数を利用できます。これらのタスクは、環境を定義した仮想マシンとは別の仮想マシンで実行される場合があるためです。

特定のジョブで、すでに宣言したワークフロー変数とは異なる値が必要な場合は、ジョブレベルの環境変数を使ってワークフローレベルの値を上書きできます。また、変数の適用範囲を特定のジョブだけに限定することもできます。

上の例のように、ジョブレベルの環境変数でJavaのバージョンを設定すると、各ステップでその変数を使えます。今後Javaのバージョンを変更する場合も、1か所を変更するだけで、ジョブ内のすべてのステップに新しいバージョンが自動的に適用されます。

GitHub Actionsを使っている今なら、Snykを簡単にGitHub Actionsに統合して、すぐにプロジェクトをスキャンできます。便利なSnyk GitHub Actionsの事前構築済みアクションをご用意しています。まだの場合はSnykアカウントに登録して、今すぐスキャンを統合しましょう。

ステップレベルの環境変数

ステップ内で変数を定義することもできます。以下は、ステップレベルの環境変数の例です。pipeline.ymlファイルのPrint nameステップを、次のコードと同じになるように変更します。

1- name: Print name
run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
env:
  BUILD: 'We are currently running the Build job'

ステップレベルの環境変数は、適用範囲を1つのステップだけに限定します。特定のステップで使用する入出力ファイルのパスを定義する場合などに便利です。上のコード例では、ステップ変数を使って出力するテキストを設定しています。

以下は、新しいジョブレベルおよびステップレベルの環境変数を追加した、GitHubワークフローYAMLファイル全体の例です。

1name: Java CI with Maven
2
3env:
NAME: 'Snyk Demo'
5
6on:
push:
  branches: [ "main" ]
pull_request:
  branches: [ "main" ]
11
12jobs:
build:
  env:
      JAVA_VERSION: '21'
16
  runs-on: ubuntu-latest
18
  steps:
  - uses: actions/checkout@v3
  - name: Set up JDK ${{env.JAVA_VERSION}}
    uses: actions/setup-java@v3
    with:
      java-version: ${{env.JAVA_VERSION}}
      distribution: 'temurin'
      cache: maven
  - name: Build with Maven
    run: mvn -B package --file pom.xml
  - name: Print name
    run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
    env:
      BUILD: 'We are currently running the Build job'

この新しいワークフローをGitHubにチェックインして、出力を確認しましょう。下の画像のように表示されるはずです。

JDK 21のセットアップ、Mavenビルド、ジョブの出力への環境変数の表示が成功したことを示すGitHub Actionsのビルドログ。

コンテキストを使って環境変数を設定すると、出力ステップが想定どおりに動作します。

コンテキストを使わずに環境変数を参照しようとすると、次のエラーが発生します。

$JAVA_VERSIONが有効なSemVer表記ではないため、Javaのセットアップに失敗したGitHub Actionsのログ

これは、setup-java actionが同じ環境にアクセスできないためです。変数を利用できるようにするには、コンテキストが必要です。

デフォルト変数とGitHubシークレットの使用

環境変数を定義するだけでなく、GitHubはワークフロー内でアクセスできるデフォルト変数も提供しています。これらの変数を使うと、GitHubリポジトリ、GitHub Actions、ワークフローのランナーなどの詳細情報を取得できます。ユーザー定義の環境変数と同じように使用できます。GitHub Actionsで利用する場合は、適切な箇所でコンテキストを使ってアクセスしてください。

最後に、環境変数の一種であるGitHubシークレットがあります。機密データを含む変数に利用できます。GitHubが暗号化し、ワークフロー内で使用できるようにします。

GitHubで暗号化された環境変数を作成するには、リポジトリのSettingsを開き、左側のメニューからSecrets and variables,、続いてActionsを選択します。次に、New repository secretをクリックし、シークレットの名前と値を入力します。下の例のようにAPI_KEYというシークレットを作成し、ランダムな値を設定してください。

新しいシークレット「API_KEY」にサンプル値が入力され、「シークレットを追加」ボタンが表示されているGitHub Actionsのシークレットページ

ワークフロー内でシークレットを使うには、GitHub Actionsに環境変数を渡すときと同じコンテキストの構文を使います。ただし、変数の前にenv.ではなくsecrets.を付けます。

1${{secrets.API_KEY}}

ワークフローのYAMLファイルで作成したprint文に${{secrets.API_KEY}}を追加します。次のコード例のようになります。

1- name: Print name
run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION. My API_KEY is ${{secrets.API_KEY}}"
env:
  BUILD: 'We are currently running the Build job'

変更をコミットしてリポジトリにプッシュします。次に、GitHubのActionsページに移動して、最新のワークフロー実行の出力を確認します。

「Print name」ステップの成功と、名前、ビルドID、Java 21のバージョン、マスクされたAPIキーを含む出力を示すGitHub Actionsのビルドログ。

ご覧のとおり、GitHubは暗号化されたシークレットの値を自動的にマスキングするため、誤って公開されることはありません。

GitHubシークレットは、パスワードやAPI認証キーなどの機密データの保存に役立ちます。シークレットを使えば、こうした値をワークフローにハードコードして外部に漏らすリスクを避けられます。GitHubが値を暗号化し、ワークフロー内のアクションに安全に渡すため、ログに平文で表示されることもありません。

まとめ

この記事では、GitHub Actionsの環境変数について解説しました。環境変数の3つの適用範囲（ワークフロー、ジョブ、ステップ）と、それぞれの範囲で変数を定義する方法を説明しました。また、コンテキストを使ってGitHub Actionsに環境変数を渡す方法と、シークレットを使って機密性の高い変数を暗号化する方法も紹介しました。

GitHub Actionsの環境変数を使うと、動的なワークフローを構築できます。ユーザー定義変数やGitHubのデフォルト変数に応じて、ワークフローの動作を変更できます。ワークフロー全体、特定のジョブやステップの動作、または実行条件を動的に変更したいときに、環境変数を活用しましょう。

この記事では、機密情報を保護する環境変数としてGitHubシークレットを使う方法も紹介しました。パスワードやAPIキーなど機密性の高い変数には、必ずGitHubシークレットを使いましょう。GitHubが値を暗号化してワークフローに渡すため、漏えいのリスクを抑えられます。

セキュリティの重要性も忘れないでください。SnykでGitHubワークフローにセキュリティをさらに加える方法をご覧ください。また、コード、コンテナ、オープンソース、IaCを包括的に保護するためのCI/CDパイプラインへのSnykの統合についてもご確認ください。