GitLabの環境変数をわかりやすく解説

CI/CD変数は、さまざまな方法で定義・使用でき、高い柔軟性を持っています。変数はジョブやパイプラインを制御する上で非常に便利で、.gitlab-ci.yml設定ファイルに値をハードコーディングせずに済みます。このブログ記事では、変数のスコープや機能を分かりやすくお伝えするため、変数の定義や使い方に関する情報を網羅的に整理し、全体像をご紹介します。記事全体をとおして、関連するドキュメントがリンクされています。

GitLab CI/CDでは、値を定義して保存することで、変数を使用してジョブをカスタマイズできます。変数を使用すれば、値をハードコーディングする必要はありません。GitLabでCI/CD変数を定義するには、**「設定」>>「CI/CD」>>「変数」**の順に移動します。または.gitlab-ci.ymlファイルで定義することも可能です。

変数は、異なるデプロイ環境（testing、staging、productionなど）におけるサードパーティサービスの設定に役立ちます。それらの環境に紐づけられたサービスは、必要なAPIエンドポイントを指す変数を変更するだけで、簡単に変更できます。また、変数を使用してジョブを設定し、ジョブ実行時にジョブ内で環境変数として利用できるようにすることも可能です。

変数と環境の関係

ソフトウェア開発プロセスには、製品をユーザー向けにリリースする前にテストするステージが含まれます。環境は、これらのステージの内容を定義するために使用されるもので、チームや組織によって異なる可能性があります。

一方、変数とは、ユーザーによる製品の操作によって変化する可能性のあるデータ値を指します。これには、年齢や好み、またはタスクフローにおける次のステップを決定する要素となるあらゆる入力が該当します。

環境変数という言葉は、皆さんもよく耳にされると思います。これは、ある環境で定義されているものの、アプリケーションの外部に存在する変数を指します。GitLab CI/CD変数を使用すると、デベロッパーはコード内で値を設定できます。変数の使用には、コードの柔軟性が保証されるという利点があります。GitLab CI/CD変数を使用すれば、コードに変更を加えることなく、特定の環境にデプロイされたアプリケーションを変更できます。これにより、アプリケーションの外部で設定の環境変数を変更するだけで、テストの実行やサードパーティサービスの統合を簡単に行えます。

CI/CD変数のスコープ

.gitlab-ci.ymlに定義された変数

GitLabには、ジョブ環境で利用する必要がある変数を追加できます。これらのCI/CD変数は、.gitlab-ci.ymlファイルのデータベースURLのような、機密性の低いプロジェクト設定を保存するために使用されます。この変数は、複数のジョブやスクリプトで再利用でき、必要な場所で値を参照できます。値を変更する場合は、変数を一度更新するだけで、変数が使用されているすべての箇所に変更が反映されます。

プロジェクトのCI/CD変数

リポジトリ固有の要件に縛られることなく、プロジェクト設定でCI/CD変数を定義できます。これにより、CI/CDパイプラインで利用できるようになります。これらの変数は、リポジトリの外部（.gitlab-ci.ymlファイルには保存されません）に保存されますが、CI/CDの設定やスクリプトで引き続き利用可能です。変数を.gitlab-ci.ymlファイル外に保存することで、これらの値のスコープをプロジェクト内のみに限定し、プロジェクトにプレーンテキストとして保存されることを防ぎます。

グループおよびインスタンスのCI/CD変数

一部の変数は、グループレベル、あるいはインスタンスレベルで適用でき、グループやインスタンス内のすべてのプロジェクトで有用となる可能性があります。グループまたはインスタンス設定で変数を定義することで、それらのスコープ内にあるすべてのプロジェクトにおいて、実際の値がわからなくても、変数を使用できるようになります。下位スコープの変数を作成する必要もありません。たとえば、複数のプロジェクトにおいて更新が必要な共通の値がある場合、1か所で最新の状態に保つことで管理しやすくなります。また、パスワードの値を実際に知らなくても、複数のプロジェクトで特定のパスワードを使用することも可能です。

環境としてのジョブとパイプライン

GitLab CI/CDの変数は、環境変数としてだけでなく、.gitlab-ci.yml設定ファイル内でパイプラインの動作を設定するためにも使用されます。この場合、特定の環境に依存しない状況でも利用できます。また、プロジェクト、グループ、インスタンスの設定に保存しておくことで、パイプライン内のジョブで利用可能になります。

以下に例を示します。

job:  
  rules:  
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  
  script:  
  - echo "This job ran on the $CI_COMMIT_BRANCH branch."  

スクリプトセクション内で使用されている変数（例：$CI_COMMIT_BRANCH）は、定義されたジョブのスコープ内で実行されます。このスコープは「ジョブ環境」と呼ばれます。つまり、ジョブが開始されると、GitLab RunnerはDockerコンテナを起動し、その環境でジョブを実行します。Runnerはその変数（および他のすべての定義済み変数やカスタム変数）をジョブに提供します。さらに、その値をログ出力に表示することも可能です。

ただし、この変数は、ジョブの実行タイミングを決定するために、if:セクションでも使用されます。ただし、そのセクション自体は環境ではないため、これらの変数を「CI/CD変数」と呼びます。CI/CDジョブを動的に設定する際に使用できるのはもちろん、ジョブの実行時に環境変数としても利用できます。

定義済み変数

GitLab CI/CDパイプラインが開始されたタイミングで、定義済み変数がすでに存在します。ユーザーは変数自体を定義せずに、コミットやプロジェクト、パイプラインの詳細などの値にすぐにアクセスできます。

カスタムCI/CD変数

GitLabでは、設定でCI/CD変数を作成する際に、変数に対してより詳細な設定オプションを利用できます。次のような追加の設定オプションを使用して、機密性の高い変数をより厳密に管理することが可能です。

環境スコープ：ある変数を特定の環境でのみ使用する必要がある場合に、その環境でのみ使用できるように設定します。たとえば、デプロイトークンをproduction環境でのみ使用できるように設定できます。

保護変数：環境スコープと同様に、デフォルトブランチなどの保護ブランチでパイプラインが実行される場合にのみ、変数を使用できるように設定できます。

変数タイプ：一部のアプリケーションでは、設定をファイル形式で渡す必要があります。そうした設定が必要なアプリケーションを利用する場合は、変数タイプを「File」に設定します。この方法でCI/CD変数を設定する場合、Runnerが環境内で変数を利用できるようにする際に、実際に一時ファイルに変数を書き出し、そのファイルパスを変数の値として保存します。その後、アプリケーションに必要なファイルパスを渡すことで設定が適用されます。

ご紹介した変数の定義方法や使用方法に加えて、GitLabでは、手動でパイプラインを実行する必要がある場合に、事前入力済みの変数を生成する機能が導入されました。事前入力済みの変数が生成されることで、エラーの発生リスクが軽減され、パイプラインを実行しやすくなります。

マスクされた変数：マスクされた変数は、変数の値が表示されないようにジョブログに隠されたCI変数です。

マスクおよび非表示化された変数：GitLab 17.4で導入されたマスクおよび非表示化された変数は、ジョブログと同じマスキング機能を利用し、設定UIでも値を非表示にします。これらの変数を機密データ（シークレットなど）に使用した場合、誤って公開されてしまう可能性があるため、推奨されません。

シークレット

シークレットとは、機密性が高く、秘密に保つべき認証情報のことを指し、以下のようなものが該当します。

• パスワード
• SSH鍵
• アクセストークン
• その他、漏洩すると組織に害を及ぼす可能性のある認証情報

GitLabでは現在、キーやトークン、その他のシークレットをプロジェクトレベルで安全に管理するために、HashiCorp Vault、Google Cloud Secret Manager、Azure Key Vaultを活用できます。これにより、CIで外部シークレットを使用することが可能です。そのため、セキュリティ上の理由から、これらのシークレットを他のCI/CD変数から分離して管理できます。

GitLabシークレットマネージャー

GitLabでは、CIにおける外部シークレットのサポートに加えて、GitLab内でシークレットを安全かつ便利に保存するためのネイティブなシークレット管理ソリューションの導入にも取り組んでいます。このソリューションは、お客様がGitLab固有のコンポーネントや環境で保存されたシークレットを使用したり、ネームスペースグループやプロジェクトレベルでのアクセスを簡単に管理したりする上でも役立ちます。

関連リンク

• GitLabネイティブシークレットマネージャーでソフトウェアサプライチェーンのセキュリティを強化

免責事項：このブログには、今後リリース予定の製品、機能、および機能性に関する情報が記載されています。ただし、それらの情報はあくまで参考のために提供されているため、購入や計画の判断材料として使用することはお控えください。すべてのプロジェクトと同様に、このブログおよびリンク先のページに記載されている項目は、変更または遅延される場合があります。製品、機能、機能性の開発、リリース、およびタイミングに関する決定権は、GitLabに帰属します。