相信有那麼一天,我們將可以像畢凱艦長一樣用嘴巴叫所有主機做事!


Cheng Wei Chen | 陳正瑋 | 艦長

DevOps Engineer / DevOps Evangelist / GitLab Hero



為何 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 中修改。

忘了啟用 Runner

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


(啟用中的 Runner。)

或者是否有啟用 Group runners。

(啟用中的 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 才行。)

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 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,就會如上圖一樣,顯示禁止符號。)

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.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.

結語

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

工商服務

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

參考資料


沒有留言:

張貼留言

不歡迎留言打廣告,所以有進行留言管理,敬請見諒。