変数が使用できる場所

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

この文書では、異なるタイプの変数がどこで、どのように使用できるかを説明します。

変数の使い方

定義された変数が使える場所は2つあります：

  1. GitLab側では、.gitlab-ci.yml。
  2. ランナー側は、config.toml。

.gitlab-ci.yml ファイル

定義 拡大できますか？ 拡張場所 説明
environment:url はい GitLab 変数の展開はGitLabの内部変数展開メカニズムによって行われます。

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

サポートされないのは、Runnerのconfig.toml で定義された変数と、ジョブのscriptで作成された変数です。
environment:name はい GitLab environment:urlと似ていますが、変数の展開は以下をサポートしていません:

- 環境の名前に基づく変数 (CI_ENVIRONMENT_NAME,CI_ENVIRONMENT_SLUG).
- 環境に関連するその他の変数 (現在はCI_ENVIRONMENT_URLのみ).
-永続化される変数.
resource_group はい GitLab environment:urlと似ていますが、変数の展開は以下をサポートしていません:

- 環境の名前に基づく変数 (CI_ENVIRONMENT_NAME,CI_ENVIRONMENT_SLUG).
- 環境に関連するその他の変数 (現在はCI_ENVIRONMENT_URLのみ).
-永続化される変数.
variables はい Runner 変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
image はい Runner 変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
services:[] はい Runner 変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
services:[]:name はい Runner 変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
cache:key はい Runner 変数の展開は GitLab Runner の内部変数展開メカニズムによって行われます。
artifacts:name はい Runner 変数の展開はGitLab Runnerのシェル環境で行われます。
scriptbefore_script、after_script はい スクリプト実行シェル 変数の展開は、実行シェル環境
only:variables:[],except:variables:[] いいえ 該当なし 変数は$variableの形式でなければなりません。 以下の変数はサポートされていません:

- 環境の名前に基づく変数 (CI_ENVIRONMENT_NAME,CI_ENVIRONMENT_SLUG).
- 環境に関連するその他の変数 (現在はCI_ENVIRONMENT_URLのみ).
-パーシステッド変数。

config.toml ファイル

注：config.toml についてはconfig.tomlRunnerのドキュメントをconfig.tomlご覧ください。
定義 拡大できますか？ 説明
runners.environment はい 変数の拡張は、Runnerの内部変数拡張メカニズムによって行われます。
runners.kubernetes.pod_labels はい 変数拡張は、Runnerの内部変数拡張メカニズムによって行われます。
runners.kubernetes.pod_annotations はい 変数拡張は、Runnerの内部変数拡張メカニズムによって行われます。

拡張メカニズム

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

  • GitLab
  • GitLabランナー
  • 実行シェル環境

GitLab内部変数拡張メカニズム

展開された部分は$variable、または${variable} 、または%variable%の形式である必要があります。それぞれの形式は、どのOS/Shellが最終的にジョブを処理するかにかかわらず、同じように処理されます。なぜなら、展開はどのRunnerがジョブを取得する前にGitLabで行われるからです。

GitLab Runner 内部変数拡張メカニズム

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

Runner は変数の展開に Go のos.Expand() メソッドを使用します。 これは、$variable と${variable}として定義された変数のみを扱うことを意味します。 また、重要なことは、展開は一度だけ行われるため、変数の定義の順序によって、ネストされた変数が機能するかどうかが変わるということです。

実行シェル環境

これは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のbefore_script全行で動作 before_scriptします。
    • scriptでは、scriptの以下の行で動作します。
    • では、after_script次の after_scriptように動作します。

after_script スクリプトの場合は可能です：

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

これらの制限は、after_script スクリプトが分離されたシェルコンテキストで実行されるためです。

永続変数

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

以下の変数は「パーシステッド」と呼ばれます：

  • CI_PIPELINE_ID
  • CI_JOB_ID
  • CI_JOB_TOKEN
  • CI_BUILD_ID
  • CI_BUILD_TOKEN
  • CI_REGISTRY_USER
  • CI_REGISTRY_PASSWORD
  • CI_REPOSITORY_URL
  • CI_DEPLOY_USER
  • CI_DEPLOY_PASSWORD

それは

環境スコープを持つ変数

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

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