為何 GitLab CI 沒有在運作？
（2021/12/25 註記：左思右想，決定棄用 Medium，未來更多文章請參閱 https://chengweichen.com）
（本文的 Canonical URL —https://chengweichen.com/2021/07/gitlab-ci-common-errors.html）
先前在擔任講師時，有時會遇見學員反應「我的 GitLab CI 沒有在運作」，出狀況的原因當然很多種，像是 .gitlab-ci.yml 的格式錯誤、內容錯誤、Runner 設定錯誤⋯⋯，本文就來條列一些常見的原因。
常見狀況
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 給此專案使用。
或者是否有啟用 Group runners。
最後，是否有為 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。
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 的管理變得更加容易了。
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》，不只能抖內艦長，還可以一併支持出版社與圖書通路商，一次抖內一舉數得喔！
