• 変数の使用法
  • .gitlab-ci.yml ファイル
  • config.toml ファイル
• 拡張メカニズム
  • GitLab 内部変数展開メカニズム
    • 入れ子の変数展開
  • GitLab Runnerの内部変数展開メカニズム
  • 実行シェル環境
• 永続変数
• 環境スコープを持つ変数

変数の使用場所

CI/CD変数のドキュメントに記載されているように、様々な変数を定義することができます。それらのいくつかはGitLabのCI/CD機能すべてに使えますが、いくつかは多かれ少なかれ制限されています。

このドキュメントでは、さまざまな種類の変数がどこでどのように使えるのかを説明します。

変数の使用法

定義された変数が使用できる場所は2つあります。それは

1. GitLab 側では、.gitlab-ci.yml ファイル。
2. GitLab Runner側、config.toml 。

.gitlab-ci.yml ファイル

GitLab 16.4 で導入された CI_ENVIRONMENT_SLUG 以外のCI_ENVIRONMENT_* 変数をサポートしました。

config.toml ファイル

config.toml についてはGitLab Runner のドキュメントを参照してください。

拡張メカニズム

拡張メカニズムは3つあります：

• GitLab
• GitLab Runner
• 実行シェル環境

GitLab 内部変数展開メカニズム

展開される部分は$variable 、または${variable} 、または%variable% の形式である必要があります。どのランナーがジョブを取得する前にGitLab内部で展開が行われるため、どのOS/Shellがジョブを処理しても、それぞれの形式は同じように処理されます。

入れ子の変数展開

• GitLab 13.10 で導入。 variable_inside_variable 機能フラグの背後でデプロイされ、デフォルトでは無効になっています。
• GitLab14.3でGitLab.comで有効に。
• GitLab 14.4でセルフマネージドで有効。
• GitLab 14.5で機能フラグvariable_inside_variable が削除されました。

GitLab はジョブの変数値をランナーに送る前に再帰的に展開します。例えば、以下のシナリオでは

- BUILD_ROOT_DIR: '${CI_BUILDS_DIR}'
- OUT_PATH: '${BUILD_ROOT_DIR}/out'
- PACKAGE_PATH: '${OUT_PATH}/pkg'

ランナーは有効で完全なパスを受け取ります。例えば、${CI_BUILDS_DIR} が/output であれば、PACKAGE_PATH は/output/out/pkgとなります。

使用できない変数への参照はそのまま残ります。この場合、ランナーは実行時に変数値の展開を試みます。たとえば、CI_BUILDS_DIR のような変数は、ランナーによって実行時にのみ認識されます。

GitLab Runnerの内部変数展開メカニズム

• サポート: プロジェクト/グループ変数、.gitlab-ci.yml 変数、config.toml 変数、トリガー、パイプラインスケジュール、手動パイプラインからの変数。
• サポート対象外: スクリプト内部で定義された変数 (例:export MY_VARIABLE="test")。

Runner は変数の展開に Go のos.Expand() メソッドを使用します。つまり、$variable と${variable} として定義された変数のみを扱います。変数の定義の順番や、GitLab でネストされた変数の展開が有効になっているかどうかによって、ネストされた変数が動作するかどうかが変わってきます。

実行シェル環境

これはscript の実行中に行われる拡張フェーズです。その動作は使用するシェルに依存します (bash,sh,cmd, PowerShell)。例えば、ジョブのscript にecho $MY_VARIABLE-${MY_VARIABLE_2}という行が含まれている場合、bash/sh では適切に処理されますが (変数が定義されているかどうかによって、空文字列やいくつかの値が残されます)、Windows のcmd や PowerShell では動作しません。これらのシェルは異なる変数構文を使用するからです。

サポートされています：

• script はシェルのデフォルト変数（例えば、$PATH は全ての bash/sh シェルに存在するはずです）と GitLab CI/CD で定義された全ての変数（プロジェクト/グループ変数、.gitlab-ci.yml 変数、config.toml 変数、トリガーやパイプラインスケジュールの変数）を使用することができます。
• script は前の行で定義されたすべての変数を使うこともできます。例えば、export MY_VARIABLE="test" ：
  • で定義した場合、before_scriptその行以降と before_script関連するscript.
  • scriptでは、script の後続行で動作します。
  • の後続after_script行で after_script動作します。

after_script スクリプトの場合は、次のようになります：

• 同じafter_script セクション内で、スクリプトの前に定義された変数のみを使用します。
• before_script とscript で定義された変数は使用しないでください。

これらの制限は、after_script スクリプトが分離された Shell コンテキストで実行されるために存在します。

永続変数

定義済みの変数の中には、「パーシステッド」と呼ばれるものがあります。

パイプラインレベルのパーシステッド変数：

• CI_PIPELINE_ID
• CI_PIPELINE_URL

ジョブレベルの永続化変数：

• CI_JOB_ID
• CI_JOB_URL
• CI_JOB_TOKEN
• CI_JOB_STARTED_AT
• CI_REGISTRY_USER
• CI_REGISTRY_PASSWORD
• CI_REPOSITORY_URL
• CI_DEPLOY_USER
• CI_DEPLOY_PASSWORD

パーシステッド変数は以下のとおりです：

• Expansion place “が定義されている場合にサポートされます：
  • ランナー。
  • スクリプト実行シェル。
• サポートされていません：
  • 拡張場所」がGitLabである定義の場合。
  • only,except,rules の変数式で。

パイプライン・トリガ・ジョブはジョブ・レベルの永続化変数を使用できませんが、パイプライン・レベルの永続化変数を使用できます。

永続化された変数の中にはトークンが含まれているものがあり、セキュリティ上の理由から定義によっては使用できません。

環境スコープを持つ変数

環境スコープで定義された変数がサポートされています。review/staging/* のスコープで定義された変数$STAGING_SECRET があるとすると、一致する変数式に基づいて、動的環境を使用する以下のジョブが作成されます：

my-job:
  stage: staging
  environment:
    name: review/$CI_JOB_STAGE/deploy
  script:
    - 'deploy staging'
  rules:
    - if: $STAGING_SECRET == 'something'