変数の使用場所

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_* 変数をサポートしました。

定義拡大可能か?拡張場所説明
after_scriptyesスクリプト実行シェル変数の展開は実行シェルの環境によって行われます。
artifacts:nameyesRunner変数の展開は GitLab Runner の Shell 環境によって行われます。
before_scriptyesスクリプト実行シェル変数の展開は、実行シェル環境
cache:keyyesRunner変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
cache:policyyesRunner変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
environment:nameyesGitLab environment:url と似ていますが、変数の展開は以下をサポートしていません:

-CI_ENVIRONMENT_* 変数
-永続化された変数
environment:urlyesGitLab変数の展開は、GitLab の内部変数展開メカニズムによって行われます。

サポートされるのは、ジョブに対して定義されたすべての変数です(プロジェクト/グループの変数、.gitlab-ci.yml からの変数、トリガーからの変数、パイプラインスケジュールからの変数)。

サポートされないのは、GitLab Runnerconfig.toml で定義された変数と、ジョブのscriptで作成された変数です。
environment:auto_stop_inyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。

代入される変数の値は、人間が読める自然言語形式の期間でなければなりません。詳しくは可能な入力をご覧ください。
except:variablesいいえ該当なし $variable

-CI_ENVIRONMENT_SLUG 変数
-永続変数
id_tokens:audyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。変数展開はGitLab 16.1で導入されました。
imageyesRunner変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
includeyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。

サポートされている変数についての詳細はUse variables with includeをご覧ください。
only:variablesいいえ該当なし $variable

-CI_ENVIRONMENT_SLUG 変数
-永続変数
resource_groupyesGitLab environment:url と似ていますが、変数の展開は以下をサポートしていません:
-CI_ENVIRONMENT_URL
-永続変数
rules:changesyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。
rules:existsyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。
rules:ifいいえ該当なし $variable

-CI_ENVIRONMENT_SLUG 変数
-永続変数
scriptyesスクリプト実行シェル変数の展開は実行シェルの環境によって行われます。
services:nameyesRunner変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
servicesyesRunner変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
tagsyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。GitLab 14.1で導入されました。
trigger およびtrigger:projectyesGitLab変数の展開はGitLabの内部変数展開メカニズムによって行われます。GitLab 15.3で導入された trigger:project の変数展開。
variablesyesGitLab/Runner変数の展開はまずGitLabの内部変数展開メカニズムによって行われ、認識できない変数や利用できない変数はGitLab Runnerの内部変数展開メカニズムによって展開されます。
workflow:nameyesGitLab

サポートされる変数は、workflowで利用可能なすべての変数です。
- プロジェクト/グループ変数。
- グローバル変数。variablesworkflow:rules:variables (ルールにマッチする場合)。
- 親パイプラインから継承された変数。
- トリガーからの変数。
- パイプラインスケジュールからの変数。

サポートされない変数は、GitLab Runnerconfig.tomlで定義された変数、ジョブで定義された変数、またはPersisted 変数です。

config.toml ファイル

定義拡大可能か?説明
runners.environmentyes変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
runners.kubernetes.pod_labelsyes変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
runners.kubernetes.pod_annotationsyes変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。

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

拡張メカニズム

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

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

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

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

入れ子の変数展開

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)。例えば、ジョブのscriptecho $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_scriptscript で定義された変数は使用しないでください。

これらの制限は、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 “が定義されている場合にサポートされます:
    • ランナー。
    • スクリプト実行シェル。
  • サポートされていません:

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

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

環境スコープを持つ変数

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

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