用 Side Project 學 CI：WeaMind 的 CI 實作策略
文章目錄
📌 這是 WeaMind 系列 的第 4 篇。
本系列以真實世界專案為背景，記錄重要技術實作與經驗分享。
〈GitHub Actions 入門：自動化 Lint、Format 與 Type Check〉一文中，我們使用了 GitHub Actions 作為 CI（持續整合）的入門工具。
同時建立了軟體開發專案中最基本且常見的 CI 流程。
接下來，我將繼續介紹，WeaMind 專案中所有實作的 CI 項目，並說明我選擇它們的原因與設計原則。
本文依據的專案程式碼版本為 v0.5.1。
從 CRUD 到 CI/CD
當我們剛開始軟體開發職涯時，確保功能與邏輯的正確，無疑是工作上的第一要務。
我們專注於「寫出正確的程式碼」（這時可能連「優雅」都還稱不上），而不太關心整個開發流程的健全度——或者說「還沒有能力」去關心。
我們忙著學習框架、查資料、確認 API response 是否符合 spec、debug 各種問題。
隨著年資增長，我們會發現一個殘酷現實：即使程式碼寫得再好，若部署流程設計不當，系統的穩定性仍然會大打折扣。
而 CI 正是連接開發與部署的關鍵橋樑，是守護程式碼品質與服務穩定的核心機制。
那麼，一個專案的 CI 應該包含哪些項目？如何在「實用」與「簡潔」之間取得平衡？
這個答案自然得因地制宜——但也有一些共通原則。
這裡我以 WeaMind 專案為例，說明我在 CI 設計上的實作與考慮。
WeaMind CI 項目一覽
我不會在這裡提供詳細的設定教學，因為每個專案的需求不同，而且只有在自己的專案中實際操作，才能真正理解每個設定的意義。
所以我們點到為止，但仍會提供一些基本的指引與參考。比起做法（問 AI 就足夠了），更重要的是其中的思路。
WeaMind 專案目前整合的 CI 項目如下，每一項都會說明實作方式與用途。
不過，一到五才是嚴格意義上的 CI；六、七則屬於自動化流程的一部分。
一、程式碼品質檢查：Lint、Format、Type Check
實作概要：
- 使用
ruff check、ruff format、pyright等指令檢查程式碼品質 - 全部定義在 ci.yml 中，執行環境使用 uv 官方容器
- 檢查會在 PR 或 push 到 main 時自動執行，避免髒 commit 混入 main
這些是上述文章的介紹重點，屬於基本中的基本。
二、覆蓋率分析報告：Codecov
實作概要：
- 使用
pytest搭配pytest-cov收集測試覆蓋率，產生coverage.xml - 在
ci.yml中設定資料自動上傳至 Codecov，產出覆蓋率分析報告 - 使用 codecov.yml 對 GitHub App 的行為進行客製化——主要是關閉成功留言、比對 patch 覆蓋率
單元測試無疑是 CI 中最重要的環節之一。
做覆蓋率分析報告的工具有很多，我選擇 Codecov 因為它與 GitHub 整合度高，且對開源專案來說非常友善。
不過，測試函式和覆蓋率報告仍需要你在 CI 流程中預先準備好。分析報告只是提供了一個視覺化結果，幫助你快速了解測試覆蓋的情況。
你可以透過 GitHub Actions 執行（需要定義自己的 YAML 檔） Codecov，或連接官方提供的 GitHub App，直接在 CI 流程中上傳覆蓋率報告即可。
我選擇後者。因為它更簡單，且已能夠自動處理許多細節。
三、Docker Build 驗證
實作概要：
- 使用
docker/setup-buildx-action建立建置環境，執行docker buildx build驗證 Dockerfile - 這項檢查對我來說是一種「部署預演」，能在尚未正式上線前提早發現問題
- 定義在
ci.yml，平行執行，不影響主流程速度
雖然尚未導入 CD，但透過建構 Image 的預演流程，能及早發現 Dockerfile 中潛在的錯誤，有助於減少部署時的風險。
四、安全掃描：GitHub CodeQL
實作概要：
- 採用 GitHub 官方 codeql.yml 設定，支援 Python 與 GitHub Actions 安全分析
- push 到 main、PR 時觸發，另外每週日也會定期執行
- 排除資料庫 migrations 等目錄（需要自行額外撰寫 codeql-config.yml 控制）
安全掃描或許不是必須，但我認為它是一種對「技術成熟度」追求的象徵。
要建立這份 YAML 檔很簡單，只要去 GitHub 倉庫設定那邊開啟該功能，系統就會自動幫你產生一份 template。
不過我還是有進行一些客製化，這部分就跟 AI 討論吧！
五、程式碼品質分析：SonarCloud
實作概要：
- 使用 SonarQube Cloud GitHub App，透過官方整合自動執行程式碼品質分析
- 分析專案中包括 code smells、bugs、security hotspots、technical debt 等事項
- 每次 PR 都會產生品質報告，幫助維持程式碼健康度
老牌的程式碼品質分析工具——SonarQube，提供比基本 lint 更深入的程式碼分析，包括複雜度、重複程度、潛在安全風險等。
對於想提升程式碼品質的專案來說，是很好的工具，且不限程式語言。
我同樣選擇使用 GitHub App 而非自己定義 Action，因為我比較懶。
自定義的話，可以更靈活地控制分析條件與操作細節。
以下兩項不算嚴格意義上的 CI，而屬於專案自動化流程的一部分。
六、相依套件更新：Dependabot
實作概要：
- 使用
dependabot.yml設定 uv 與 GitHub Actions 的週期性更新 - 設定 commit message 格式與自動 rebase，減少手動維護成本
- 每週自動檢查並自動建立 PR（如果有新版），讓套件更新變得可控且透明
套件的管理是專案維護中容易被忽略的環節之一。套件版本過舊可能帶來安全風險，但手動更新又容易忘記。
Dependabot 讓這個過程自動化，同時透過 PR 機制讓每次更新都經過 CI 驗證。
更重要的是，它讓「更新」這件事變得可見、可追蹤，而不是藏在某個角落的技術債。
七、自動 GitHub Release
實作概要：
- 使用
softprops/action-gh-release，當 tag 以v*命名時自動建立 release 並附上 notes - 定義在
auto-release.yml，適合小型專案做版本整理
其實就是取代手動發布 Release的流程。
主要是受到 Will 保哥的《頁問 AskPage》和其它開源專案的啟發。
先是實作了半自動的 CHANGELOG 更新機制，後來乾脆連 Release Notes 都一起自動產生。
實際的效果就是：每次 push 帶有v*的 tag 時，會自動建立對應的 GitHub release。
雖然格式稍嫌呆板，但感覺就是兩個字——愉悅！
流程概覽
為方便回顧，再次整理 WeaMind 專案中各 CI 流程的關鍵步驟。
核心 CI 流程（每次程式碼時變更觸發）
- 程式碼品質檢查：使用 Lint、Format、Type Check 確保程式碼風格一致性
- 測試與覆蓋率上傳：執行單元測試並上傳覆蓋率報告至 Codecov
- Docker Build 驗證：驗證 Dockerfile 的正確性，確保容器化部署不出錯
- 安全掃描：GitHub CodeQL 掃描，檢查潛在安全風險（push + 週期性觸發）
- 程式碼品質分析：使用 SonarCloud 進行深入的程式碼品質分析
輔助自動化工具
- 相依套件更新：透過 Dependabot 自動更新相依套件，減少手動維護成本
- 自動發布：使用 GitHub Release 自動建立版本釋出
最後附上 CI 流程的示意圖：
WeaMind CI 流程圖
結語
以上就是 WeaMind 專案目前的 CI 設計全貌。
這套設計不是為了炫技，而是出於對品質的堅持，讓一個產品型 Side Project 能在成長過程中穩定運作——並累積信任。
如果你也有在開發 Side Project，不妨參考本文實作幾項 CI 流程，建立屬於自己的品質防線。
CI 不必一次到位，但每一步都在為未來的穩定與信任打底。
如果這篇文章對你有幫助，歡迎到 WeaMind GitHub 給我一個星星支持
你的 star 是我持續分享技術文章的動力😇