Day03 - Pipeline 的變數宣告 Variables - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2025 iThome 鐵人賽

DAY 3

DevOps

GitLab CI 2025：深入玩轉流水線與實戰紀錄系列第 3 篇

Day03 - Pipeline 的變數宣告 Variables

17th鐵人賽 gitlab gitlab-ci gitlab ci

墨嗓

團隊兩貓一犬一條龍小隊

2025-09-12 15:41:31

72 瀏覽

分享至

在過去系列的文章中，曾經談過GitLab CI 怎麼從外帶入參數到流水線中？談變數 variable當時提到，變數也可以在手動觸發時帶入，但當時，必須要透過開發者自行透過額外的文件等資訊，使用者才能夠輸入正確的變數名稱及可適用的變數參數。

在這一篇內容中，將介紹關於 GitLab CI/CD YAML 中，對於上述問題的解決方法，將會提到 variables:description、variables:value 以及 variables:options 來更明確的標示手動觸發流水線時，關於變數可直接參考的資訊。

首先，先以以下的範例舉例：

Day03_01_variables .gitlab-ci.yml

default:
  image: ubuntu:24.04

variables:
  DEPLOY_ENV: "Prod"
  DEPLOY_MODULE:
    value: "Apple"
    description: "Production module name"
    options: ["Apple", "Banana", "Orange"]

demo_job:
  script:
    - echo "variable Deploy_ENV value is ${DEPLOY_ENV}"
    - echo "variable DEPLOY_MODULE value is ${DEPLOY_MODULE}"

在上面的範例中，於 variables 裡，第一個看到的是 DEPLOY_ENV對應數值 Prod，這是在過去 GitLab CI/CD YAML 的基本用法，使用者可以在新建流水線的介面，於變數名稱(Input variable key)的地方，輸入 DEPLOY_ENV 並在後方的變數數值(Input variable value)的欄位，輸入預期的數值如：Dev。

GitLab Pipeline 建立變數的畫面

可以發現，這樣的方法無論是變數的名稱或變數可使用的數值，都必須透過開發者額外的文件或紀錄使用者才能正確地輸入。因此自 GitLab 後續的版本中開始提供：variables:value 參數的預設值、variables:description 參數的說明描述以及variables:options參數可選用的選項。

如何使用

可以看到上面的範例關於變數 DEPLOY_MODULE 的部分：

  DEPLOY_MODULE:
    value: "Apple"
    description: "Production module name"
    options: ["Apple", "Banana", "Orange"]

其中 variables 中的參數DEPLOY_MODULE 其預設值為 Apple 關於這個欄位的說明描述為"Production module name"並且，它有三個選項，分別是 Apple、Banana 以及 Orange。

在這樣的設定之後，於新建流水線時，就可以看到如下圖，當有設定這些參數之後，就可以在新建流水線時，讓使用者建立時避免使用錯誤的參數。

GitLab Pipeline 輸入變數，有搭配 description 及 value 與 options 的畫面

使用上的限制

關於 variables 變數本身，變數名稱必須只能由數字、英文字及底線()所組成，且數值的部分，只能是字串。另外，也要特別注意，有些作業環境變數名稱的第一個字元只能是英文字。
關於 variables:description，這個變數描述，只能用在所有流水線的 variables 區段，而不能使用在個別 Job 的 variables 中。另外，當有設置變數的description 後，這個變數就會存在在非手動觸發的流水線中，並且其數值為空字串。不過 description 可以支援 Markdown 格式，所以可以在描述的文字中使用如粗體字**、刪除線~~ 甚至是標題 # 等等的 Markdown 語法來加強描述的說明。
關於 variables:value，與 description 一樣，只能使用在流水線的預設 variables 區段中。
關於 variables:options，與上面兩個參數一樣，只能用在流水線的預設 variables 區段中，options 對應的內容，必須要是字串的 Array ，且如果有設定 value 中的數值，則 value 的數值必須要存在在這個 Array 中，大小寫也必須一致否則會產生錯誤。另外，使用 options 必須搭配 description 一起使用，否則 options 的設定會失效，在觸發流水線時，看不到選項。

One More Thing 關於 `variables` 的小功能

使用 variables 的時候，有時候會透過兩個變數，作字串串接，例如以下例子：

variables:
  VAR1: value1
  VAR2: value2 $VAR1
  VAR3:
    value: value3 $VAR1
    expand: false

default_job:
  script:
    - echo "VAR1 value is ${VAR1}"
    - echo "VAR2 value is ${VAR2}" # value2 value1
    - echo "VAR3 value is ${VAR3}" # value3 $VAR1

以上面的範例來說 Script 的第二行 echo "VAR2 value is ${VAR2}"， VAR2 就可以透過字串串接變成 value2 value1增加一些變數使用上的彈性。

但如果因為業務需求，不用變數字串串接的特性，而要如實的呈現這個文字呢？ GitLab 在 15.6 的版本之後提供了 variables:expand 這個參數，預設為 true 當設定為 false 的時候，就不會把變數替換成對應的數值。如上面範例中的第三行 echo "VAR3 value is ${VAR3}" 就會如實的印出 VAR3 value is value3 $VAR1 因為上面的 variables 在 VAR3 設定了 expand: false。上面的範例，完整輸出的內容如下：

$ echo "VAR1 value is ${VAR1}"
VAR1 value is value1
$ echo "VAR2 value is ${VAR2}"
VAR2 value is value2 value1
$ echo "VAR3 value is ${VAR3}"
VAR3 value is value3 $VAR1

總結

在新版本的 GitLab CI/CD YAML 中，關於 variables 的更新，解決了過去使用者必須依靠文件才能正確輸入變數名稱與值的痛點。透過 variables:value、variables:description 以及 variables:options，開發者可以在 .gitlab-ci.yml 中直接定義變數的預設值、說明文字及可選項目。這樣一來，當使用者手動觸發流水線時，介面就能提供更直觀的提示與選擇，降低輸入錯誤的機率。但使用上有一些限制使用的過程中需要特別注意。另外可以記住 expand 的參數特性，在有需要的時候使用。我是墨嗓（陳佑竹），期待這次的內容能帶給你實用的啟發與幫助。