在上一季介紹過 parallel:matrix 平行化陣列的語法，對於整理重構只有參數差異的工作非常的好用，實務上，我個人經常使用 parallel:matrix 這個語法做 GitLab CI/CD YAML 內容的重構。但 GitLab 開始支援 parallel:matrix ，後一直有個語法上的困擾，當後續的工作與 parallel:matrix 中的工作有相依關係時，會被迫無法使用，因為 needs 的關聯條件中，並無法使用 parallel:matrix，終於，在 GitLab 16.3 版本釋出中，GitLab 開始支援 needs:parallel:matrix 的語法，讓 needs 可以相依於 parallel:matrix。

needs:parallel:matrix 該如何使用，有什麼情境呢？

直接以之前 parallel:matrix 的案例來說明，這是一個模擬需要在不同作業系統中編譯不同位元數應用程式的範例。

default:
  image: ubuntu:24.04

BuildProcess:
  stage: build
  before_script:
    - echo "prepare build env"
  after_script:
    - echo "clean up env"
  script:
    - echo "build ${BUILD_OS} ${PRODUCT_BIT} application"
    - touch ${BUILD_OS}_${PRODUCT_BIT}.txt
  artifacts:
    paths:
      - ${BUILD_OS}_${PRODUCT_BIT}.txt
  parallel:
    matrix:
      - BUILD_OS: ['Ubuntu', 'AlmaLinux']
        PRODUCT_BIT: ['32bit', '64bit']

在這案例中，假設不同的作業系統會有不一樣的測試程序時，可能就需要不一樣的工作環境來進行測試，這時候原本的寫法就沒辦法在 build 的階段使用 parallel:matrix，那麼，在新的語法中，如何解決這個問題呢？

假設會有兩個測試工作，一個測試 BUILD_OS 中的 Ubuntu 另外一個測試 AlmaLinux ，那個就可以依據 needs:parallel:matrix 如下表示：

TestProcess:Ubuntu:
  needs:
    - job: BuildProcess
      parallel: 
        matrix:
          - BUILD_OS: Ubuntu
            PRODUCT_BIT: ['32bit', '64bit']
  script:
    - echo "Test on Ubuntu"
    - ls *.txt

TestProcess:AlmaLinux:
  needs:
    - job: BuildProcess
      parallel: 
        matrix:
          - BUILD_OS: AlmaLinux
            PRODUCT_BIT: ['32bit', '64bit']
  script:
    - echo "Test on AlmaLinux"
    - ls *.txt

以 TestProcess:Ubuntu 這個 Job 為例，可以看到對應的輸出內容僅有自兩個 BUILD_OS 為 Ubuntu 的 Artifact。

$ echo "Test on Ubuntu"
Test on Ubuntu
$ ls *.txt
Ubuntu_32bit.txt
Ubuntu_64bit.txt

使用上的限制

needs:parallel:matrix 使用上，是有一些細節需要注意的，以上面的案例來說如果把 matrix 的內容條件改為以下的內容，在 Pipeline editor 中，就會顯示錯誤訊息，表示，找不到對應的工作相依：

This GitLab CI configuration is invalid: TestProcess:Ubuntu2 job: undefined need: BuildProcess: 32bit, Ubuntu.

TestProcess:Ubuntu2:
  needs:
    - job: BuildProcess
      parallel: 
        matrix:
          - PRODUCT_BIT: ['32bit', '64bit']
            BUILD_OS: Ubuntu
  script:
    - echo "Test on Ubuntu"
    - ls *.txt

因此條件中的 matrix 順序，一定要與需求來源的宣告順序一致，才能正確的相依。

總結

在可以使用 needs:parallel:matrix 語法之後，相信可以讓很多的 CI/CD YAML 又變得可以寫得更簡潔容易維護，你也有使用 parallel:matrix 語法嗎？那麼你一定要知道 GitLab 16.3 之後提供的 needs:parallel:matrix。我是墨嗓（陳佑竹），期待這次的內容能帶給你實用的啟發與幫助。

參考範例

• Day 15 01 needs parallel matrix

參考連結

• Day18 - GitLab CI 如何透過參數幫忙執行參數不同但內容相同的工作？工作並行陣列 - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天
• GitLab CI/CD YAML reference - needs:parallel:matrix