昨天把測試、Type Check 與正式建置整合成同一個指令：

npm run check

這個指令在本機可以正常執行，但如果提交前忘了跑，錯誤仍然可能跟著 commit 一起進入 Pull Request。

今天要把同一個指令搬到 GitHub Actions。之後每次建立或更新 Pull Request，GitHub 都會在一個乾淨的環境重新驗證專案。

CI 解決什麼問題？

本機驗證依賴開發者記得執行，也可能受到電腦上既有套件或檔案影響。

CI（Continuous Integration，持續整合）則會在指定事件發生時自動執行固定流程，例如：

更新 Pull Request
-> GitHub 建立乾淨的執行環境
-> 安裝相依套件
-> 執行 npm run check
-> 顯示成功或失敗

CI 不能保證程式完全沒有 bug，它只能確保我們設定的檢查真的有執行。不過至少不必再依賴一句「我有在本機跑過」。

Workflow 要放在哪裡？

GitHub Actions 的 workflow 會放在：

.github/workflows/

今天預計新增：

.github/workflows/ci.yml

內容只需要完成四件事：

1. 取得 repository 的程式碼
2. 建立符合專案需求的 Node.js 環境
3. 使用 npm ci 安裝 lockfile 指定的套件
4. 執行 npm run check

GitHub 官方也建議 Node.js 專案在 workflow 中執行和本機相同的 build 與 test 指令，可以參考 Building and testing Node.js。

為什麼是 npm ci？

這個專案已經有 package-lock.json，CI 應該根據 lockfile 安裝確定的版本：

npm ci

它和日常加入套件時使用的 npm install 用途不同。npm ci 不會替我們重新決定相依套件版本；如果 package.json 和 lockfile 不一致，它會直接失敗，讓問題提早被發現。

Workflow 何時執行？

今天會讓 workflow 在兩種情況執行：

• 有 Pull Request 指向 main 時
• 有 commit 推送到 main 時

第一項負責在合併前檢查變更，第二項則確認合併後的主分支仍然正常。

只在本機建立 commit 不會觸發 GitHub Actions，必須把 branch 推送到 GitHub，並建立或更新 Pull Request。

今天使用的 Prompt

我會在 Issue Tracker repository 開啟新的 Codex 任務，輸入：

請替目前 Issue Tracker 新增最小可用的 GitHub Actions CI workflow。

請先閱讀：
- package.json 與 package-lock.json
- README.md
- AGENTS.md
- 現有測試與 build 設定
- repository 目前的預設分支與 Git 狀態

請完成：
1. 新增 `.github/workflows/ci.yml`
2. 在 Pull Request 指向 main，以及 commit 推送到 main 時觸發
3. 使用 GitHub-hosted Ubuntu runner
4. checkout repository
5. 根據專案實際需求選擇仍受支援的 Node.js 版本
6. 使用目前 GitHub 官方文件中仍受維護的 checkout 與 setup-node major version
7. 啟用 setup-node 提供的 npm cache
8. 使用 `npm ci` 安裝相依套件
9. 執行昨天建立的 `npm run check`
10. 實際檢查 workflow YAML 與現有 package scripts 是否一致

限制：
- 不新增、移除或升級任何 npm 套件
- 不修改產品功能與測試
- 不加入資料庫、外部服務、祕密、部署或 artifact 上傳
- 不在 workflow 內重複拆寫 test、Type Check 與 build
- 如果無法從 repository 判斷 Node.js 版本，先說明證據與建議，不要默默猜測

完成後請回報：
- 新增了哪個檔案
- workflow 的觸發時機
- 每個 step 的用途
- Node.js 與 action 版本的選擇依據
- CI 最後會執行哪個專案指令
- 目前 Git 狀態

這段 prompt 的回覆和執行

為什麼不讓 CI 重寫三個命令？

也可以在 workflow 直接寫：

- run: npm test
- run: npm run build

但這會讓本機與 CI 各自維護一份檢查清單。以後如果加入 lint，只改到其中一邊，兩個環境就會產生落差。

所以 workflow 只負責執行：

npm run check

真正包含哪些品質檢查，仍由 package.json 統一管理。

確認綠燈

Codex 完成後，先檢查 diff，確認只有預期的 workflow 檔案，再 commit 並推送目前的 branch。

接著建立一個 Draft Pull Request。GitHub Actions 開始執行後，可以點進 PR 的 Checks 區域確認：

• workflow 是否有被觸發
• npm ci 是否成功
• npm run check 是否真的執行測試與 build
• 最後是否顯示綠色勾勾

這是我的 repo，在裡面的 commit 找到 "add ci workflow" 就是這篇文章寫完時的狀態。

今日小結

今天把本機的 npm run check 接到 GitHub Actions，讓 Pull Request 每次更新時都會在乾淨環境重新執行測試、Type Check 與 build。