変数が使用できる場所
CI/CD変数のドキュメントに記載されているように、様々な変数を定義することができます。 その中にはGitLabのCI/CD機能全てに使えるものもあれば、多かれ少なかれ制限のあるものもあります。
この文書では、異なるタイプの変数がどこで、どのように使用できるかを説明します。
変数の使い方
定義された変数が使える場所は2つあります:
- GitLab側では、
.gitlab-ci.yml
。 - ランナー側は、
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のシェル環境で行われます。 |
script before_script 、after_script
| はい | スクリプト実行シェル | 変数の展開は、実行シェル環境 |
only:variables:[] ,except:variables:[]
| いいえ | 該当なし | 変数は$variable の形式でなければなりません。 以下の変数はサポートされていません:- 環境の名前に基づく変数 ( CI_ENVIRONMENT_NAME ,CI_ENVIRONMENT_SLUG ).- 環境に関連するその他の変数 (現在は CI_ENVIRONMENT_URL のみ).-パーシステッド変数。 |
config.toml
ファイル
config.toml
についてはconfig.toml
Runnerのドキュメントを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
それは
-
エキスパンション・プレイス」の定義に対応:
- ランナーです。
- スクリプト実行シェル。
- サポートされていません:
- Expansion place “がGitLabである定義について。
-
only
、except
変数式で。
環境スコープを持つ変数
環境スコープで定義された変数がサポートされています。review/staging/*
のスコープで定義された変数$STAGING_SECRET
があるとすると、一致する変数式に基づいて、動的環境を使用する以下のジョブが作成されます:
my-job:
stage: staging
environment:
name: review/$CI_JOB_STAGE/deploy
script:
- 'deploy staging'
only:
variables:
- $STAGING_SECRET == 'something'