変数を使用できる場所

CI/CD変数ドキュメントで説明されているように、さまざまな変数を定義できます。すべてのGitLab CI/CD機能に使用できる変数もありますが、使用範囲がある程度制限されているものもあります。

このドキュメントでは、さまざまなタイプの変数をどこでどのように使用できるかについて説明します。

変数の使用

定義された変数は、次の2つの場所で使用できます:

1. GitLab側（.gitlab-ci.ymlファイル内）。
2. GitLab Runner側（config.toml内）。

.gitlab-ci.ymlファイル

config.tomlファイル

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

展開メカニズム

次の3つの展開メカニズムがあります:

• GitLab
• GitLab Runner
• 実行Shell環境

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

展開対象の部分は、$variable、${variable}、%variable%のいずれかの形式で記述する必要があります。各形式は、どのOS/Shellがジョブを処理するかに関係なく同じように処理されます。これは、Runnerがジョブを取得する前に、GitLabで展開が行われるためです。

ネストされた変数展開

GitLabは、ジョブ変数の値を再帰的に展開してから、Runnerに送信します。例として、次のシナリオについて説明します:

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

Runnerは、有効で完全な形式のパスを受け取ります。たとえば、${CI_BUILDS_DIR}が/outputの場合、PACKAGE_PATHは/output/out/pkgになります。

利用できない変数への参照は、そのまま残されます。この場合、Runnerはランタイムに変数値を展開しようとします。たとえば、CI_BUILDS_DIRのような変数は、Runnerがランタイムにのみ認識します。

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

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

Runnerは、変数展開にGoのos.Expand()メソッドを使用します。つまり、$variableおよび${variable}として定義された変数のみを処理します。もう1つ重要な点として、展開は1回しか行われないため、ネストされた変数は、変数の定義の順序によって、またGitLabでネストされた変数の展開が有効になっているかどうかによって、動作する場合としない場合があります。

アーティファクトおよびキャッシュのアップロードの場合、Runnerは変数展開にGoのos.Expand()ではなく、mvdan.cc/sh/v3/expandを使用します。これは、mvdan.cc/sh/v3/expandがパラメータ展開をサポートしているためです。

実行Shell環境

これは、script実行中に発生する展開フェーズです。その動作は、使用されるShell（bash、sh、cmd、PowerShell）によって異なります。たとえば、ジョブのscriptにecho $MY_VARIABLE-${MY_VARIABLE_2}という行がある場合、bash/shでは適切に処理されるはずですが（変数が定義されているかどうかに応じて、空の文字列や値に置き換えられる）、WindowsのcmdまたはPowerShellでは異なる変数構文を使用するため動作しません。

サポート対象:

• scriptでは、Shellでデフォルトとして利用可能なすべての変数（たとえば、すべてのbash/sh Shellに存在するはずの$PATH）と、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コンテキストで実行されるためです。

永続変数

一部の定義済み変数は、永続変数と呼ばれます。永続変数のサポート条件は次のとおりです:

• サポート対象: 展開場所が次の場所に定義されている場合:
  • Runner。
  • スクリプト実行Shell。
• サポート対象外:
  • 展開場所がGitLabに定義されている場合。
  • rules変数式内。

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

永続変数の一部にはトークンが含まれており、セキュリティ上の理由から、一部の定義では使用できません。

パイプラインレベルの永続変数:

• CI_PIPELINE_ID
• CI_PIPELINE_URL

ジョブレベルの永続変数:

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

環境スコープを持つ変数

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

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