為何 GitLab CI 沒有在運作?

先前在擔任講師時,有時會遇見學員反應「我的 GitLab CI 沒有在運作」,出狀況的原因當然很多種,像是 .gitlab-ci.yml 的格式錯誤、內容錯誤、Runner 設定錯誤⋯⋯,本文就來條列一些常見的原因。

(本文同步發表於 Medium。)

常見狀況

以下逐一分享幾十種常見的異常狀況。

一、CI/CD Pipeline 設定檔的檔名錯誤

GitLab 預設的 CI/CD Pipeline 設定檔為 .gitlab-ci.yml,要注意前面有一個 .,以及是 yaml 檔案 .yml,不要太順手寫成 .yaml。另外就是 GitLab 也能設定改用別的檔名作為 CI/CD Pipeline 的設定檔,因此也要注意是不是有啟用這項設定,搞不好你的專案還真的已經改用 gitlab.yaml 當作 CI/CD Pipeline 設定檔了喔~

二、CI/CD Pipeline 設定檔的存放位置錯誤

續上,除了檔名之外,CI/CD Pipeline 設定檔的存放位置也很重要。預設的存放位置是專案的根目錄,存放位置也同樣可以自行修改。

【小提醒】CI/CD Pipeline 設定檔的檔名及存放位置都可以在 GitLab 的 Porject > Settings > CI/CD > General pipelines > CI/CD configuration file 中修改。

GitLab WebUI

三、忘了啟用 Runner

CI/CD Pipeline 要能運作,你必須要為 Project 啟用 GitLab Runner 才行。在 Porject > Settings > CI/CD > Runner 中確認是否有 Enable 任何一台 Specific runner 給此專案使用。

(啟用中的 Runner。) (啟用中的 Runner。)

或者是否有啟用 Group runners。

(啟用中的 Group Runner。) (啟用中的 Group Runner。)

最後,又或者是否有為 Project 啟用 Shared runners。

【小提醒】Specific runner 是特別針對各 Project 啟用的 Runner,必須單獨在各個 Project 的 Settings > CI/CD > Runners 中啟用;Group runners 則是預設隸屬在同一個 Group 之下的 Project 都能使用它,當然你也可以在 Settings > CI/CD > Runners 單獨為 Project Disable Group runners;最後 Shared runners 是 gitlab.com 官方免費提供的 Runner,不想自行架設 Runner 的人,也可以自由選用,但要注意的是根據 gitlab.com 帳號之付費等級差異,你可以免費使用 Shared runners 的時數會有所不同。在補充一點,如果你是自行架設 GitLab Server,你也可自行架設 Shared runners 供你的使用者們運用。

四、沒有為 CI Job 指派正確的 Runner

在 GitLab CI 我們可以為 CI Job 設置 tags: 這項參數,藉此控制 CI Job 只能被哪些 GitLab Runner 執行。因此如果有為 CI Job 設置 tags:,但卻沒有提供符合這些 tags 的 GitLab Runner,也會導致 CI/CD Pipeline 卡住不運行。

缺少可以執行 untagged jobs 的 Runner 續上,由於不是所有的 CI Job 都會設置 tags:,那麼這些缺少 tags: 的 CI Job 也需要有一個設置 Run untagged jobs 的 Runner 來處理這些 Job。

(在個別的 Runner 設定中,可以找到這一個選項,如果 CI/CD Pipeline 含有 untagged jobs,記得也要架設此種 Runner 才行。) (在個別的 Runner 設定中,可以找到這一個選項,如果 CI/CD Pipeline 含有 untagged jobs,記得也要架設此種 Runner 才行。)

五、GitLab Runner 處在 Paused 的狀態

這同樣也是 GitLab Runner 的個別設定,當 GitLab Runner 成功架設並註冊至 GitLab 之後,預設會是 Active 的狀態,但你也可以手動將 Runner Paused,讓它暫時不要處理 Job。因此也是有可能發生,Runner 因為某些原因正在維護中,被人暫時 Paused,導致沒有 Runner 可以處理 CI/CD Pipeline。例如,艦長在幫負責 Production deploy 的 Runner 升級 Ansible 版本時,就曾經暫時 Paused,在那段期間,就不會有 Production deploy 相關的 CI Job 能夠執行。

GitLab WebUI

六、忘記某個 GitLab Runner 早已下線

還有一種狀況是,原本提供服務的 Runner,根本就已經下線,當然就沒有 Runner 能夠運行 CI/CD Pipeline。這種狀況比較容易發生在當你有多個 Specific runner 的時候。

因為 Specific runner 是跟著 Project 設定的,也就比較容易發生,在 Project A 註冊了 Specific runner A,然後在 Project B 則 Enable Specific runner A,讓 Project B 也能使用相同的 Runner A 運行 CI/CD Pipeline。但隨著時間流逝,也許在 Project A 結案時也順手將 Runner A 下線了,於是 Project B 就發生沒有 Runner 可用的狀況。在早期的 GitLab 版本其實滿容易發生這種狀況,好在 GitLab 後來提供了 Group Runners 的功能,讓 Runner 的管理變得更加容易了。

(已下線的 Runner,但並未被移除的 Runner,就會如上圖一樣,顯示禁止符號。) (已下線的 Runner,但並未被移除的 Runner,就會如上圖一樣,顯示禁止符號。)

七、GitLab Runner 版本過舊

與 Runner 有關的還有一個可能是 GitLab Runner 的版本問題,但其實這個問題不太容易遇到。

因為 GitLab Runner 的更版是具備兼容性的,因此除非你的 GitLab Runner 與 GitLab Server 兩者的版本年代差了十萬八千里,不然基本上都是能正常運作的。再者,現在大家幾乎都是用 Container 來架設 Runner,因此想要定期更新 Runner 版本並不困難,如果有人真的遇到這種狀況,還請與艦長分享一下你的經驗談。

八、CI Job 與 Stage 沒有正確對應

在 CI/CD Pipeline 的規劃方面,有一個狀況也很常見,特別是當你編寫了較大、較複雜的 CI/CD Pipeline 時比較容易遇到,即是沒有為 CI Job 設置正確的 Stage。

stages:
- build
- test

composer install:
  script:
  - composer install

phpunit:
  script:
  - phpunit

以上面的 .gitlab-ci.yml 為例,雖然有規劃 Stage: build,但卻沒有為 CI Job 設置 stage:,因此最後產生的 CI/CD Pipeline 就會變成下圖的模樣,因為 GitLab CI 為 CI Job 預設的 Stage 是 test

GitLab CI WebUI

九.gitlab-ci.yml 撰寫錯誤

好吧,這一項可能是廢話,但很實在(喂),總之,使用工具前務必詳閱使用說明書,GitLab CI 有自己規定的參數,如果不小心打錯字,或是將 Job 分配給一個不存在的 Stage,都會出現 CI configuration is invalid 的錯誤。此外由於 .gitlab-ci.yml 是 YAML 格式,每個人都曾遇過的 YAML 縮排問題也要小心。好在 GitLab 官方已提供越來越多的輔助工具,如善用 CI Lint、Pipeline Editor 這些功能,即可有效避免撰寫錯誤的狀況。

十、忘了啟用 Auto DevOps + 忘了刪除 .gitlab-ci.yml

最後一個特殊的狀況就是 Auto DevOps。也許你想要的不是自己規劃 CI/CD Pipeline,而是想要使用酷炫的 Auto DevOps 功能,那麼記得要去 Settings > CI/CD > Auto DevOps 啟用它,並且刪除你不小心放進 Project 內的 .gitlab-ci.yml,因為預設是沒有 CI/CD 設定檔在 Project 內,才會自動產生 Auto DevOps 的 CI/CD Pipeline。

(介面上已有提示,The Auto DevOps pipeline runs if no alternative CI configuration file is found.) (介面上已有提示,The Auto DevOps pipeline runs if no alternative CI configuration file is found.

結語

本文條列了一些會導致「GitLab CI 沒有在運作」常見狀況,這些都是初接觸 GitLab CI 時有可能遭遇到的情況,希望能有助於大家度過 GitLab CI 的新手期。如果你有遇到本文以外的異常狀況,也歡迎與我分享喔!

工商服務

如果你覺得艦長寫的文章對你有產生幫助,歡迎抖內(Donate)艦長,讓艦長可以將原本用來養家活口的餘力多分一些投入在社群分享上。咦,你說網頁上沒看到任何類似 Buy Me a Coffee 的連結?那不妨買一本艦長的著作《和艦長一起 30 天玩轉 GitLab》,不只能抖內艦長,還可以一併支持出版社與圖書通路商,一次抖內一舉數得喔!

參考資料

更多文章