流程定位

App 部署的風險集中在不可變 artifact 與外部 gate。IPA、APK、AAB 或桌面安裝包一旦被使用者安裝，團隊需要靠 hotfix、remote config、kill switch 或服務端相容性止血；store review、簽章憑證與 phased rollout 會決定錯誤版本能否快速收斂。

Version 階段負責讓 artifact 可追溯。App crash report、客服回報與 store console 都依賴 version / build number；版本號對應 commit 與 workflow run 時，事故定位可以直接回到發布紀錄。

App signing 階段負責維持發布信任鏈。簽章憑證、provisioning profile、keystore 與 notarization credential 都是發布能力；它們要用 secret 管理、權限隔離、輪替與備援流程保護。

Test 階段負責覆蓋目標裝置條件。App 測試要依實際使用者分佈選擇 OS、裝置、權限狀態、網路條件與升級路徑；只跑 emulator smoke test，通常抓不到真機權限、背景限制或升級資料遷移問題。

Store review 階段負責處理外部 gate。審核可能因 metadata、隱私揭露、權限使用、付款政策或 crash 被拒；CI/CD 文件要記錄誰能處理審核回覆、哪些變更需要重新提交。

Rollout strategy 階段負責控制新版本擴散速度。分批發布的觀察指標包含 crash rate、登入、購買、同步、推播與核心流程完成率；達到停損條件時應暫停 rollout，先讓已受影響範圍維持可控。

Recovery 階段負責處理已安裝版本。App 常見止血工具是 remote config、feature flag、kill switch、server-side compatibility、hotfix build 與要求使用者升級；每個工具都要在事故前實作，事故時才有路可走。

多版本共存契約

多版本共存是 App 發布的基本前提。後端 API、資料格式、推播 payload 與 remote config 都要支援一段時間的新舊 client，因為使用者更新節奏不受團隊完全控制。

這些契約要在 CI 或 release checklist 裡被驗證。若只靠後端「盡量相容」，App 發布失敗會在使用者更新後才暴露，回復成本會比 web 或後端高。

Release checklist

Release checklist 的責任是把外部 gate 與內部 gate 接起來。App 發布牽涉商店、憑證、客服、行銷與後端相容，因此 checklist 應該是流程契約，不只是提醒清單。

1. 確認 version、build number、commit 與 artifact 對應。
2. 確認 signing secret、profile 或 keystore 仍有效。
3. 跑 unit、UI、device matrix 與 upgrade test。
4. 檢查 API / remote config / push payload 多版本相容。
5. 上傳 internal / beta track，跑 smoke test。
6. 提交 store review，記錄審核狀態。
7. 用 phased rollout 推進，觀察 crash-free rate 與核心指標。
8. 觸發停損條件時暫停 rollout、關閉功能或準備 hotfix。

這個順序讓 App 發布從「把包丟上去」變成可觀測流程。每一步都對應一個失敗路由，事故時能知道下一個可執行動作。

下一步路由

• App 部署總覽：回 App 部署 CI/CD。
• 簽章概念：讀 App Signing。
• Gate 原理：讀 CI gate 與 workflow 邊界。

流程定位

Data pipeline 的風險集中在資料副作用。API 發布錯誤通常會表現成 request failure；資料任務錯誤可能把錯誤結果寫進 warehouse、feature store、報表或下游模型，並在很久之後才被看見。發布流程要把 correctness check 放到 deploy 前後。

Build 階段負責固定執行邏輯。dbt model、Spark job、Flink processor、Airflow DAG 或 SQL transform 都需要能追到 commit 與 dependency，讓歷史資料重跑時能確認使用哪一版邏輯。

Validation 階段負責檢查資料契約。Schema check、sample run、contract test、row count、null ratio、distinct count 與 business invariant 都可以作為 gate；重點是讓輸出變更在下游消費前被看見。

Deploy 階段負責切換任務版本。Scheduler、trigger、checkpoint location 與 credential 都會影響新版本是否真正接管；部署後要確認下一次 run 用的是新版本，並保留舊版本停止或恢復路徑。

Backfill 階段負責補算歷史資料。Backfill 應有時間範圍、節流、checkpoint、停損條件與對帳策略，避免一次掃完整個歷史區間壓垮上游或把錯誤大規模寫入下游。

Rerun 階段負責修復失敗 run 或錯誤區間。Rerun 要定義輸出覆寫、去重、idempotency 與下游通知；同一段資料被跑兩次時，結果應可預期。

Recovery 階段負責處理錯誤資料已被消費的情況。資料 pipeline 的 rollback 常常採用 forward fix、重新計算、標記污染區間與通知下游重新讀取。

Backfill 控制面

Backfill 控制面的責任是限制歷史補算的影響範圍。歷史資料量通常遠大於日常增量；沒有控制面的 backfill 會同時衝擊計算成本、上游讀取、下游寫入與資料正確性。

這些控制項要寫進 workflow 或 runbook。若 backfill 只能靠工程師現場下 SQL，事故時很難保證每次操作都有相同邏輯。

Rerun 判讀

Rerun 判讀的責任是確認重跑是否會造成二次傷害。資料任務失敗後，最危險的動作是未確認輸出語意就直接重跑。

這張表讓 rerun 從「再跑一次」變成有條件的恢復策略。資料正確性比任務綠燈更重要；綠燈只代表 job 完成，不代表輸出可信。

下一步路由

• Data pipeline 部署總覽：回 Data Pipeline 部署 CI/CD。
• Migration 概念：讀 Migration。
• Gate 原理：讀 CI gate 與 workflow 邊界。

流程定位

Desktop client 的風險集中在作業系統信任鏈與更新通道。macOS、Windows、Linux 對簽章、安裝包格式與安全提示的要求不同；同一份 source 通常會產生多個平台 artifact，因此 workflow 要把平台 matrix、簽章 secret 與 Release Channel 拆清楚。

Build 階段負責產生平台專屬 artifact。Flutter Desktop、Electron 與 Tauri 的輸出格式不同，但共同要求是每個 artifact 都能追到 commit、workflow run 與 dependency lock。

Signing 階段負責讓 OS 信任安裝包。Windows code signing certificate、macOS Developer ID、timestamp server 與 Linux package signing key 都是發布能力；secret 應放在受控環境，並限制能觸發 signing job 的分支與 reviewer。

Notarize 階段負責處理 macOS 信任 gate。macOS app 即使完成簽章，也常需要 notarization 與 stapling；CI 要把 notarization log 保存下來，否則使用者看到 Gatekeeper 警告時很難回溯。

Release 階段負責把 artifact 放到正確 Release Channel。Internal、beta、stable 與 enterprise channel 的 gate 不同；CI/CD 要避免未審核的 beta artifact 被 stable feed 取用。

Update 階段負責維持升級路徑。Update Feed、delta package、signature、minimum supported version 與 rollback channel 要一起設計；更新壞掉時，使用者可能卡在需要人工修復的版本。

Recovery 階段負責止血。桌面客戶端常用方式是撤下 update feed、發布 hotfix、切換 rollback channel、停用 remote feature 或要求最低版本；每種方式都依賴 app 內建相容支援。

平台差異判讀

平台差異判讀的責任是讓 CI matrix 對應真實發布風險。桌面發布除了確認「三平台都 build 成功」，還要確認每個平台的安裝、啟動、更新與卸載行為。

這張表的用途是避免平台細節被單一「desktop build」欄位抹平。每個 OS 的失敗代價不同，CI 應保留平台專屬 gate。

Update feed 契約

Update Feed 契約的責任是讓已安裝使用者安全升級。Auto-update 需要簽章、版本比較、channel、最低版本與回退策略共同成立，才能讓新版本 URL 進入 feed。

1. Feed 只指向已簽章且已驗證的 artifact。
2. Stable feed 只接收 stable release，beta feed 只接收 beta release。
3. App 啟動時能處理 feed 暫時不可用。
4. Delta update 失敗時能 fallback 到 full installer。
5. 錯誤版本要能從 feed 撤下，並讓未更新使用者停止取得。
6. 已更新使用者要有 hotfix 或 rollback channel。

這些條件讓更新通道具備操作性。若 app 只知道「看到新版就下載」，錯誤 feed 會把事故放大到所有啟動中的使用者。

下一步路由

• Desktop 部署總覽：回 Desktop Client 部署 CI/CD。
• App 發布通用觀念：讀 App 簽章、商店審核與分批發布流程。
• 簽章術語：讀 App Signing。

流程定位

IaC 的風險集中在共享狀態與不可逆資源。應用部署失敗常可回退 artifact；基礎設施變更可能刪除資料、替換節點、改掉 IAM 權限或讓 state 與真實環境分叉。發布流程應讓 reviewer 在 apply 前看到「將要改什麼」，並讓 apply 後能確認「環境是否真的符合宣告」。

Plan 階段負責產生可審查差異。Plan 是 reviewer 判斷資源替換、權限擴大、資料刪除與網路暴露的主要材料。CI 應保留 plan artifact，讓 apply 使用同一份輸入與版本。

Review 階段負責把風險放到正確 owner。平台、資安、資料庫或服務 owner 應依資源類型參與審核；高風險變更需要額外 gate，例如 maintenance window、人工 approval 或雙人審核。

Apply 階段負責把宣告狀態寫入環境。State Lock、credential、workspace 與環境變數都要固定；partial apply 或 timeout 後，要先判斷 state 與真實資源是否一致，再決定下一步。

Verify 階段負責確認平台可用。Apply 成功只代表 provider API 接受變更；仍需要 connectivity test、policy check、service smoke test、DNS / certificate check 或 cluster health，確認服務真的能跑。

Infrastructure Drift 階段負責發現宣告與現況分叉。手動 hotfix、雲端 console 調整、外部 controller 或 provider 預設值都可能造成 drift；drift detection 要定期執行，並把修復責任導回宣告檔。

Recovery 階段負責處理失敗套用。IaC 回復不一定是 git revert 後 apply；可能需要 import、state mv、taint / untaint、手動修復資料資源或 forward fix。流程要先保護資料與服務，再修正宣告與 state。

Plan review 判讀

Plan review 的責任是讓變更影響在 apply 前被看見。Reviewer 應依資源語意判斷，讓 diff 行數退居輔助訊號。

這張表讓 review 從「有人按 approve」變成風險判讀。IaC review 的價值在於提前看見不可逆或高代價變更。

Drift 處理路由

Drift 處理的責任是把現況重新帶回可管理狀態。Drift 發現後不應直接 apply 覆蓋，因為 drift 可能是事故 hotfix、外部系統自動調整或宣告檔過期。

1. 確認 drift 來源：人工 hotfix、provider 預設、外部 controller 或宣告過期。
2. 判斷 drift 是否仍需要保留：若是真實修復，應回寫到 IaC。
3. 判斷 apply 是否會破壞服務：特別看 replacement、destroy、權限與 network。
4. 修正宣告或 state：必要時使用 import、state mv 或 provider-specific repair。
5. 重新 plan，確認差異收斂到預期。

這個路由讓 drift 修復具備審查性。直接在 console 裡補到看起來正常，會讓下一次 CI apply 把修復覆蓋掉。

常見反模式

反模式的共同問題是把 IaC 降成指令自動化，忽略它承擔的狀態治理責任。

下一步路由

• IaC 部署總覽：回 IaC / Platform 部署 CI/CD。
• 環境保護：讀 Environment Protection。
• Gate 原理：讀 CI gate 與 workflow 邊界。

流程定位

Image deployment 的風險集中在「看似同名、實際不同」的產物漂移。latest、mutable tag、重新 build 與跨 registry promotion 都可能讓 staging 測過的 image 不等於 production 跑的 image。嚴謹流程應以 Image Digest 或 immutable tag 作為 artifact 身分。

Build 階段負責封裝 runtime。Multi-stage build、dependency cache、base image pinning 與 build secret 處理會直接影響安全性；CI 應能在乾淨 runner 上重建 image，避免開發機狀態被帶入。

Tag 階段負責支援不同查詢情境。Commit SHA 適合事故追溯，semver 適合 release 溝通，Image Digest 適合 runtime 精準鎖定；production 判讀應以 digest 為準，tag 只作為人類入口。

Scan 階段負責把風險分流。Vulnerability scan、secret scan、license scan 與 SBOM 不應只是報表；流程要定義哪些風險阻擋發布、哪些風險允許例外、例外誰審核、何時重新評估。

Container registry 階段負責保存與推進 image。Registry 要處理權限、retention、immutability、promotion 與垃圾回收；若 production 直接從 feature branch push 的 tag 拉 image，供應鏈邊界就失去治理。

Runtime handoff 階段負責把已驗證 image 交給部署平台。Kubernetes、ECS、Compose 或其他 runtime 都應指向已驗證 digest 或 immutable tag，並把 health、readiness、resource limit 與 rollback 連到同一次 release。

Tag 與 digest 策略

Tag 策略的責任是讓人查得到、機器鎖得住。單一 tag 很難同時滿足可讀性、可追溯與不可變三個需求，因此實務上常搭配多個 tag 與 digest。

Production deployment 應能從 running pod 或 task 反查 image digest，再反查 registry metadata、scan report、workflow run 與 source commit。這條查詢路徑是 incident response 的基本能力。

Scan gate 分流

Scan gate 的責任是讓安全訊號變成可操作路由。掃描工具會產生大量結果，沒有分流規則時，團隊會在兩種壞狀態間搖擺：全部阻擋導致發不出去，全部忽略導致掃描失去信任。

這個分流讓 scan 成為 gate。例外流程要有 owner 與到期日，讓例外維持可追蹤、可重新評估。

常見反模式

反模式的共同問題是讓 image 身分失去穩定錨點。當 image 身分漂移，測試結果、掃描結果與 runtime 狀態會彼此分叉。

下一步路由

• Image 部署總覽：回 Docker / Image 部署 CI/CD。
• Registry 術語：讀 Container Registry。
• 後端 runtime 部署：讀 後端部署 CI/CD。

流程定位

Serverless 的風險集中在觸發條件。函式部署成功只代表新版本存在，實際風險會在 HTTP request、queue message、topic event、scheduled job 或 edge request 觸發時出現。發布流程要能區分「版本建立成功」「alias 切流量成功」「事件來源行為正確」三件事。

Package 階段負責產生可執行 bundle。Serverless 常見失敗是本機 dependency 可用，但打包後缺檔、runtime target 不符、native extension 不相容或 layer 版本漂移；CI 應在接近目標 runtime 的環境做 smoke test。

Version 階段負責建立不可變版本。直接覆蓋 $LATEST 會讓事故追溯困難；正式流量應指向 version 或 Function Alias，讓 rollback 能把 alias 切回前一個已知版本。

Function Alias / traffic 階段負責控制流量切換。HTTP function 可以用少量權重 canary；queue trigger 則要觀察 batch failure、retry、dead-letter 與 downstream side effect，因為同一個錯誤 event 可能被重試多次。

Permission 階段負責限制 blast radius。Serverless 函式容易因部署方便而累積過大 IAM 權限；每個 function 應只拿到必要 resource、secret 與 network access，並把 production secret 與 preview / staging 隔離。

Event Source 階段負責定義失敗重送語意。Queue、topic、object storage、HTTP 與 scheduler 的錯誤行為不同；CI/CD 文件要記錄 retry 次數、dead-letter destination、batch size、concurrency limit 與 replay 條件。

Recovery 階段負責止血。Serverless 常見止血方式是 alias rollback、停用 trigger、降低 concurrency、清理毒訊息、重放事件或 forward fix；只回退 code 版本不一定能處理已經排入 queue 的事件。

事件來源判讀

事件來源判讀的責任是找出失敗是否可重試。Serverless 常被誤判為「函式自己失敗」，但實際根因可能是 event schema、權限、上游重試或下游限流。

這張表讓 release failure 能被導向正確 owner。若 event schema 變了，修 function 可能只是表面補丁；真正的 gate 要加在 publisher contract 或 sample event validation。

最小發布 gate

Serverless workflow 的最小 gate 應覆蓋 package、permission、event 與 alias。缺其中一段，部署成功就可能只是建立了一個尚未被驗證的函式版本。

1. Package bundle，固定 runtime target 與 dependency。
2. 對 bundle 執行 unit / contract / sample event test。
3. 用 least privilege policy 做 deploy dry run 或 policy diff。
4. 發布 immutable function version。
5. 用 alias 將少量流量導向新版本。
6. 觀察 error、latency、retry、DLQ 與 downstream 指標。
7. 指標穩定後提高 alias 權重或完成切換。
8. 指標觸發 tripwire 時切回 alias、停用 trigger 或啟動 repair。

這個流程把 Serverless 發布從「上傳函式」提升成可回復流程。對事件驅動函式而言，trigger 與 retry policy 是發布契約的一部分。

下一步路由

• Serverless 部署總覽：回 Serverless 部署 CI/CD。
• Rollout 概念：讀 Rollout Strategy。
• 失敗處理：讀 CI 失敗到修復發布流程。

流程定位

前端部署的風險集中在 build time。後端服務可以在 runtime 讀取設定、檢查資料庫與逐步接流量；前端靜態產物多半在 build 階段就把 route、asset path、環境變數與 feature flag 預先寫入 bundle。CI/CD 的判讀重點因此是「被部署的 artifact 是否就是已驗證的那一份」。

Build 階段負責建立可驗證產物。真實服務裡，npm run dev 成功不代表 production build 能成功；CI 應固定 Node 版本、package manager、lockfile、build command 與必要環境變數，讓 artifact 可以從乾淨環境重建。

Browser test 階段負責驗證使用者實際會看到的頁面。Playwright、visual diff、a11y check 或 smoke test 應盡量對 build 後的靜態站執行，避免 dev server 的 fallback、熱更新或寬鬆路由遮蔽 production 問題。

Preview environment 階段負責把 PR 變成可操作畫面。Preview URL 要能追到 PR、commit 與 workflow run，reviewer 才能把畫面問題回報到正確版本；preview 也要隔離 production 資料與 credential，避免預覽環境變成未受控入口。

Deploy 階段負責把 artifact 放到 hosting 或 CDN。前端部署失敗常出現在 cache policy、SPA fallback、base URL、static route 與 sourcemap 權限；deploy 成功只代表檔案上傳完成，仍需要檢查入口頁、核心路由與 asset 是否能從公開網址載入。

Rollback strategy 階段負責恢復上一份可用靜態產物。前端 rollback 表面上只是切回舊檔案，但若 API schema、build time config 或 CDN cache 已經變動，舊頁面仍可能呼叫不相容的後端，因此 rollback 要搭配 smoke test 與 cache purge。

常見失敗路由

前端 CI 紅燈要先判斷失敗在 build、browser test、preview 還是 production deploy。不同層的修復入口不同；把所有紅燈都當成「重跑 workflow」會掩蓋 artifact 漂移與 cache 問題。

這張表的用途是縮短定位時間。前端部署問題常被誤判成「CDN 壞掉」或「瀏覽器快取」，但更常見的根因是 build artifact、route 與 cache policy 的契約沒有明確寫進 pipeline。

最小 workflow 骨架

前端 workflow 應把 build、test、preview 與 deploy 的資料流顯性化。下面是概念骨架，重點在 artifact handoff 的方向，特定平台語法是次要的。

 1jobs:
 2  build:
 3    steps:
 4      - run: npm ci
 5      - run: npm run build
 6      - uses: actions/upload-artifact
 7        with:
 8          name: web-dist
 9          path: dist
10
11  test:
12    needs: build
13    steps:
14      - uses: actions/download-artifact
15        with:
16          name: web-dist
17      - run: npm run test:e2e:static
18
19  preview:
20    needs: test
21    if: github.event_name == 'pull_request'
22    steps:
23      - uses: actions/download-artifact
24        with:
25          name: web-dist
26      - run: npm run deploy:preview
27
28  deploy:
29    needs: test
30    if: github.ref == 'refs/heads/main'
31    steps:
32      - uses: actions/download-artifact
33        with:
34          name: web-dist
35      - run: npm run deploy:production

這個骨架讓 deploy 依賴 test，也讓 test 與 deploy 使用 build job 產生的同一份產物。若專案需要在不同環境注入設定，要明確區分 build time config 與 runtime config，避免同一份 artifact 被重新 build 成另一份內容。

Tripwire

Tripwire 的責任是提醒前端 workflow 需要重切。當同一類問題反覆出現，局部補命令通常只能暫時遮住資料流錯位。

• Preview 常和 production 不一致：把 preview 改成部署 build artifact，讓 preview job 沿用同一份產物。
• E2E 測試通過但 production 壞：把 E2E 改到 static artifact 或 production-like server 上執行。
• rollback 依賴人工找舊 commit：保留 release artifact 與版本索引，讓回退指向明確產物。
• CDN cache 問題反覆出現：把 HTML cache、asset cache 與 purge 策略寫進 deploy checklist。

下一步路由

• 前端部署總覽：回 前端部署 CI/CD。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 本 blog 靜態站案例：讀 本 blog 專案部署。

流程定位

後端部署的主要風險是有狀態依賴。前端 artifact 可以直接回退上一份靜態檔，後端服務一旦寫入新資料、消費 queue message 或呼叫外部 side effect，rollback 就不再只是換回舊 image。發布流程要先定義新舊版本如何短暫共存，再決定 migration 與流量切換順序。

Build 階段負責產生可部署服務。服務版本要能從 runtime 反查 commit、workflow run、image digest 與 migration 版本，讓事故時能快速定位哪一次變更進入環境。

Contract test 階段負責驗證跨邊界相容。API response、database schema、queue message 與 config key 都是契約；只測 service 內部函式，通常抓不到新舊版本並存時的破壞性變更。

Migration 階段負責推進資料狀態。安全 migration 通常採 expand-and-contract：先加相容欄位或表、部署可讀新舊格式的程式、回填資料，最後移除舊格式。直接在同一次 release 刪欄位與切程式，會讓 rollback 失去空間。

Rollout strategy 階段負責控制新版本接到的流量。Rolling、canary 與 blue-green 都需要可信 readiness；readiness 應檢查服務能否接流量，而不只是 process alive。

Rollback strategy 階段負責定義失敗時的處理路由。後端 rollback 常見做法是 app rollback、config rollback、traffic rollback 或 forward fix；資料已被新程式寫入時，forward fix 往往比直接資料回滾安全。

Migration 順序

Migration 順序的責任是保留相容窗口。資料結構變更應讓至少兩個相鄰程式版本能共存，避免部署中途任何一端先完成都造成服務不可用。

1. 新增向前相容 schema，例如新增 nullable column 或新表。
2. 部署可同時讀舊欄位與新欄位的程式。
3. 執行 backfill 或 background migration。
4. 切換讀取來源或寫入路徑。
5. 觀察穩定後移除舊欄位、舊 index 或舊 message 格式。

這個順序的價值是可停止。若第 3 步回填異常，可以暫停 backfill，不必立即回退 app；若第 4 步切換後錯誤率升高，可以先切回舊讀取路徑，再評估資料修補。

Rollout 判讀

Rollout 判讀要同時看技術指標與業務副作用。服務能啟動不代表能安全接流量；API error、queue lag、database lock、第三方 API 錯誤與核心業務漏斗都可能是發布問題。

這些訊號要先接到發布流程。若指標只存在 dashboard 裡、workflow 不知道如何判讀，團隊仍會在事故當下靠人工臨場決策。

常見反模式

反模式的共同問題是把後端部署當成單一 deploy 動作。後端發布的本質是多個相依狀態的協調流程。

下一步路由

• 後端部署總覽：回 後端部署 CI/CD。
• Migration 術語：讀 Migration。
• Gate 原理：讀 CI gate 與 workflow 邊界。

為什麼需要這條通道

CLI binary 跟函式庫的下游使用脈絡不同。函式庫需要被同語言專案 import，自然走 registry（npm install、pip install、cargo add）。CLI binary 的目標讀者是「只想跑這個工具」的人，他們不一定有對應 toolchain、不想花時間編譯，也不會接受「先裝開發環境才能用」的入場門檻。

Binary release 的契約是：上游負責編譯、下游負責下載。這條契約成立需要三個前提同時滿足：

1. CI 能在多平台 cross-compile 出可執行檔（macOS x64/arm64、Linux x64/arm64、Windows x64）
2. 編譯產物有穩定 URL，下游可以用一行 shell 命令取得
3. 安裝過程不依賴開發環境（不需要 git clone、不需要 build toolchain）

達成這三點需要一個 release 工具鏈把 build matrix、artifact 上傳、installer script 產生包成一個 tag-driven 的 workflow。Rust 生態用 cargo-dist、Go 生態用 goreleaser、語言中性的方案則是手刻 GitHub Actions matrix。三者觸發條件相同（push semver tag）、產物落點相同（GitHub Release assets），只在 build pipeline 細節有差。

Tag-driven release 的鏈路

Tag-driven 的核心設計：push tag 是發版意圖的唯一訊號。這條因果鏈每一環都要實作起來才會通：

1維護者 push tag vX.Y.Z         ↓
2                                →  release.yml workflow 觸發（tag pattern 匹配）
3                                →  cross-compile to N platforms（GitHub Actions matrix）
4                                →  打包成 <pkg>-x86_64-apple-darwin.tar.xz 等 N 個 archive
5                                →  產生 <pkg>-installer.sh / .ps1（內嵌指向上述 archive 的 download URL）
6                                →  建立 GitHub Release vX.Y.Z
7                                →  上傳所有 archive + installer 為 release assets
8                                →  GitHub 自動把 vX.Y.Z 的 assets 也鏡射到 /releases/latest/download/

這條鏈路上每個節點都是一塊要設定的工作：

• Tag pattern：cargo-dist 預設匹配 **[0-9]+.[0-9]+.[0-9]+*，符合 semver 才會觸發
• Build matrix：在 Cargo.toml 的 [workspace.metadata.dist] 宣告 targets = [...]，cargo-dist 會展開成對應的 GitHub Actions runners
• Pre-build hooks：如果編譯前需要產生程式碼或下載資料，要透過 github-build-setup 注入（zhtw-mcp 的案例就是要先跑 gen-s2t-tables.py 產生 s2t_data.rs）
• Installer 範本：cargo-dist 內建 shell / powershell / homebrew / npm 等多種 installer 產生器，在 installers = [...] 設定
• /releases/latest/download/ alias：GitHub 自動提供，指向 latest non-prerelease release 的 asset；prerelease 不會更新這個 alias

這也解釋了為什麼 git tag dev 或單純 commit 到 main 都不會發版 — 那不符合 tag pattern、不是發版意圖。

第一次搭 cargo-dist 的實作步驟

從零開始的維護者視角，Rust binary 專案要搭 cargo-dist 大致是這幾步：

1. 裝 cargo-dist CLI：cargo install cargo-dist（或從它自家的 installer 裝）
2. 跑 dist init：互動式問答，選 targets、installers、CI provider（GitHub Actions），它會在 Cargo.toml 寫入 [workspace.metadata.dist] 並產生 .github/workflows/release.yml
3. 檢查產出：release.yml 是 auto-generated、開頭會標 # This file was autogenerated by dist，不要手改，下次 dist generate 會被覆蓋
4. 設定 pre-build hook（如果需要）：在 Cargo.toml 加 github-build-setup = "build-setup.yml"，把編譯前要跑的步驟寫在 .github/build-setup.yml（這個檔不會被 dist generate 覆蓋）
5. 設定 preflight gate（重要）：把現有的 main CI workflow 加上 workflow_call trigger，在 Cargo.toml 設 plan-jobs = ["./.github/workflows/main.yml"]，讓 release pipeline 在 cross-compile 前先確認測試全綠
6. 推第一個 prerelease tag 試水溫：git tag v0.1.0-alpha.1 && git push origin v0.1.0-alpha.1，看 release.yml 跑出來的 matrix 是不是全綠
7. 確認 installer script 可用：在乾淨機器上跑 curl ... /releases/download/v0.1.0-alpha.1/<pkg>-installer.sh | sh（注意 prerelease 要用完整 tag URL、不是 latest）
8. 推第一個正式 tag：跑 v0.1.0，這時 /releases/latest/download/ alias 才會生效
9. 更新 README：把 installer 安裝命令寫上去；正式版發出後就能用 latest URL，prerelease 階段要寫完整 tag URL
10. 後續維護：bump version → tag → push，cargo-dist 自動處理；只有改 [workspace.metadata.dist] 時才需要重跑 dist generate

第 5 步的 preflight gate 是新手最容易漏的關。沒有它的話、main 紅燈時你還是能 push tag、cargo-dist 還是會跑 cross-compile、爛 binary 還是會推到所有人。workflow_call 反向 reuse 這個 pattern 在 CI gate 與 workflow 邊界 有更完整討論。

Installer script 模式的契約

curl ... | sh 是這條通道的常見下游入口。這個入口要成立，前提是上游提供可驗證產物、下游執行前有最小安全檢查。

cargo-dist 產生的 installer 命令長這樣：

1curl --proto '=https' --tlsv1.2 -LsSf \
2  https://github.com/<owner>/<repo>/releases/latest/download/<pkg>-installer.sh | sh

逐項拆解 curl 的 flag：

-f 那個 flag 是這條鏈路的安全點：沒有它的話、如果 release URL 暫時 404，GitHub 的 404 HTML 會被 pipe 到 sh 然後爆出一堆語法錯誤；有 -f 時 curl 會直接 exit 22、sh 不會被呼叫，使用者看到的是清楚的錯誤碼。這就是為什麼 cargo-dist 產生的範本預設帶 -f、不能省。

PowerShell 版本（irm | iex）的等價契約相同 — Invoke-RestMethod 對 404 也會丟 exception、不會把 HTML 餵給 Invoke-Expression。

Installer script 自己的內部行為：偵測平台、下載對應 archive、解壓、放到 ~/.local/bin 或 ~/.cargo/bin、視需要更新 PATH。這部分由 cargo-dist 範本生成、跨專案幾乎一致、維護者不需要手寫。

最小安全基線（教學案例版）

教學案例可以示範 curl | sh，但可維護版本要同時提供「下載、驗證、執行」路徑，讓使用者在高風險環境可切換到可審計流程。

 1# 1) 下載 installer 與 checksum
 2curl --proto '=https' --tlsv1.2 -LsSf \
 3  -o /tmp/<pkg>-installer.sh \
 4  https://github.com/<owner>/<repo>/releases/download/vX.Y.Z/<pkg>-installer.sh
 5curl --proto '=https' --tlsv1.2 -LsSf \
 6  -o /tmp/<pkg>-checksums.txt \
 7  https://github.com/<owner>/<repo>/releases/download/vX.Y.Z/<pkg>-checksums.txt
 8
 9# 2) 驗證 checksum（sha256sum 或 shasum 擇一）
10sha256sum -c /tmp/<pkg>-checksums.txt --ignore-missing
11# shasum -a 256 -c /tmp/<pkg>-checksums.txt
12
13# 3) 執行 installer
14sh /tmp/<pkg>-installer.sh

這條路徑的責任分工是：

1. 上游：發布 installer 與對應 checksum（或 provenance）。
2. 下游：先驗證再執行。
3. 文件：同時提供快速路徑與可審計路徑，並標明適用情境。

Pre-release（early adopter）通道

第一個正式 release 之前，pipeline 本身需要先被驗證。這時 prerelease tag（v0.1.0-alpha.1、v0.1.0-rc1 之類）就派上用場：

• 作為 pipeline 自身的測試：tag 推下去能跑出多平台 binary，代表 cargo-dist 設定正確
• 給 early adopter 試用：願意當先驅者的使用者可以用完整 tag URL 取得 binary
• 不污染 latest alias：GitHub 的 releases/latest/download/ 只指向 non-prerelease，所以 prerelease 不會「假發版」

代價是 prerelease 沒有 stable URL — 每個版本要寫完整 tag、不能用 latest。所以 README 安裝段落在 v0.1.0 出來之前要寫：

1# Pre-release example（給 early adopter）
2curl --proto '=https' --tlsv1.2 -LsSf \
3  https://github.com/<owner>/<repo>/releases/download/v0.1.0-alpha.1/<pkg>-installer.sh | sh

正式 v0.1.0 出來之後再切回 latest URL。這是 zhtw-mcp issue #35 討論裡 hydai 提的折衷方案，能讓社群在 pipeline 完備前先試用、又不誤導不明就裡的使用者以為正式版已就位。

zhtw-mcp 案例：社群協作把 release pipeline 搭起來

zhtw-mcp 的 issue #35 跟 PR #40 是這條搭建過程的活案例。整個討論的時間軸：

1. dlackty 提 issue #35：建議導入 cargo-dist + Homebrew、列出建議 targets、指出 s2t_data.rs 需要 pre-build hook
2. 作者 jserv 回應：認同方向，但坦承自己 Rust 經驗有限、這個專案部分目的就是為了學 Rust 生態，邀請社群提 PR 推進
3. hydai 開 PR #40：第一次用 cargo-dist，自己也在學，誠實表示「想知道方向對不對，希望熟手能接手」，並引用自己之前用 knope 手刻 release 的另一個 repo 作為對照
4. jserv 提到 installer URL 失效：README 已經寫了 releases/latest/download/...，但還沒有正式 release，建議用 pre-release 給 early adopter
5. hydai 提議 v0.1.0-alpha.1：作為 early adopter 通道、提醒 prerelease 沒有 latest alias、要用完整 tag URL

這個討論留下幾個值得學的點：

• 公開承認還在學是好事：jserv 直接說「我 Rust 經驗有限、我也在學」、hydai 說「我第一次用 cargo-dist」，這比假裝專家有效率多了。社群協作的核心是大家都看到同一個未完成狀態、一起補。
• README 先寫安裝命令再補 release 是常見順序：把 release 路線當作目標釘出來、再倒推實作，是刻意的設計。先寫文件再補 pipeline 的順序也讓 issue #35 / PR #40 更容易聚焦。
• 特殊 build hook 是 cargo-dist 的明確支援點：zhtw-mcp 需要在編譯前跑 gen-s2t-tables.py 產生 s2t_data.rs，這正好是 github-build-setup 設計給的場景。如果你的 repo 有類似「編譯前要產生程式碼／下載資料」的需求、不必為此放棄 cargo-dist。
• Pre-release 是 pipeline 學習期的合理工具：先用 v0.1.0-alpha.1 把 pipeline 跑通、把問題暴露出來，比等到一切完美才發版更有效率。

跟著這個 issue 串看完一輪、可以得到一個從零搭 cargo-dist 的真實參照框架，比官方文件更貼近實際遇到的問題。

Homebrew 通道：cargo-dist 怎麼幫你出 formula

brew install 是 macOS 使用者最熟的安裝路線，但 Homebrew 有兩種發版形式：

cargo-dist 預設支援的是後者（tap）。設定方式是在 [workspace.metadata.dist] 加：

1installers = ["shell", "powershell", "homebrew"]
2tap = "<your-github-username>/homebrew-<tap-name>"

然後在 GitHub 開一個叫 homebrew-<tap-name> 的 repo（命名規則是 Homebrew 強制的），cargo-dist 會在每次 release 自動 push 一個更新過的 formula 到那個 repo。下游使用者只要：

1brew tap <your-github-username>/<tap-name>
2brew install <pkg>

要走 homebrew-core 是另一個層級的事 — 需要套件夠成熟、有穩定使用者基數、有清楚的 license、過 homebrew-core maintainer 的 review。多數新專案先做 tap、累積使用者跟成熟度後再考慮 core。

上線前的最後檢查

第一個正式 v0.1.0 推出去之前最後跑一遍：

• Prerelease tag（v0.1.0-alpha.1 之類）跑過 release.yml、cross-compile matrix 全綠
• 從乾淨機器跑 README 寫的 installer 命令、從下載到執行整條順
• Pre-build hook（如果有）在所有 platform 都能跑、不依賴特定 OS
• Preflight gate 的 workflow_call reuse 確實 block 住紅燈 main
• README 的 installer URL 跟實際 asset 命名規則一致（cargo-dist 會用 <pkg>-installer.sh、不要寫成 install.sh）
• Changelog 跟 tag 對齊（cargo-dist 會把 changelog 抓進 release notes）
• 有提供可審計安裝路徑（下載 + checksum/provenance 驗證 + 執行）

第一條 v0.1.0 推出去後 releases/latest/download/... alias 才會生效、那時就能把 README 改成 latest URL、徹底完成這條通道的搭建。

來源與規格

• cargo-dist 官方文件：https://opensource.axo.dev/cargo-dist/
• cargo-dist GitHub Action / 生成流程：https://github.com/axodotdev/cargo-dist
• GitHub Releases 與 latest 行為：https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
• zhtw-mcp 案例 issue：https://github.com/sysprog21/zhtw-mcp/issues/35
• zhtw-mcp 案例 PR：https://github.com/sysprog21/zhtw-mcp/pull/40

下一步路由

• 想理解整體 release 類型分類：回 Package / Library Release CI/CD。
• 想理解 workflow_call 的反向 reuse：讀 CI gate 與 workflow 邊界。
• 想理解 release workflow 紅燈時的處理：讀 CI 失敗到修復發布流程。
• 想理解 artifact 可信度：讀 Artifact Provenance。

概念位置

CI Pipeline 位在開發提交、pull request 與主線保護之間，常由 lint、test、build、security check 組成。

可觀察訊號

• PR 需要依賴檢查結果決定能否合併。
• 團隊需要一致的失敗判讀入口。
• 本機通過但共享流程失敗時，需要明確定位差異。

接近真實服務的例子

前端專案會把 markdown lint、browser test 與 production build 放在同一套 CI 驗證入口。後端專案則可能加入 contract test、migration check 或 image scan。

設計責任

CI Pipeline 要定義必跑檢查、失敗回饋路由與執行時間上限，讓綠燈具備可發布前提。

失敗後先看什麼

失敗後第一步是定位 workflow 與 job。CI/CD 系統會把一次 push、pull request、tag 或 release 拆成多個 workflow，每個 workflow 下面又有多個 job；真正的下一步取決於是哪一層失敗。

Lint / format 失敗代表靜態契約沒有通過。常見情境是程式格式、文件格式、型別檢查、schema 或設定規則不符合規範。這類失敗的修復路徑通常很短：讀錯誤訊息、修正來源、必要時跑 formatter，再提交修正。

Test 失敗代表某個行為或契約沒有符合預期。這類失敗要先看 report、screenshot、trace、device log 或 error context，確認是功能真的回歸、測試假設過期，還是測試環境缺少 production-like artifact。直接改測試前，要先確認測試原本守的是哪個使用者或系統行為。

Build 失敗代表 pipeline 尚未產生可部署產物。這類失敗通常來自編譯錯誤、bundle 設定、依賴版本、環境變數、template 或資源路徑。修復時以專案定義的 production build 命令作為最小重現入口。

Deploy 失敗代表發布動作沒有完成。這類失敗需要先區分 artifact 是否存在、發布通道權限是否正確、環境保護是否放行。若測試與 build 已成功，deploy 失敗多半是發布通道問題；若 artifact 沒有產生，應回到 build 或 package 階段。

本機重現流程

本機重現的責任是讓修復建立在同一個驗證條件上。CI 是用乾淨環境執行的一組命令；只要能在本機跑出同樣的失敗，修復就能被快速驗證。

1make build
2make test
3make deploy-dry-run

Build 命令驗證 production artifact 是否能產生。這一步應該接近 CI 使用的 build 入口，避免開發模式遮蔽 production 問題。

Test 命令驗證產物或程式行為。前端可能是 browser test，後端可能是 integration / contract test，App 可能是 device test，Docker 可能是 image scan 或 smoke test。

Deploy dry-run 命令驗證發布前條件。高風險部署至少要能檢查 artifact、權限、環境與版本資訊；沒有 dry-run 的專案，也應保留對等的 preflight check。

修復與重新觸發

修復流程的核心是用新 commit 讓 CI 重新驗證。一般流程不需要刪掉失敗 commit，也不需要 force push；失敗 commit 留在歷史裡，後續 fix commit 會形成清楚的修復脈絡。

1. 讀失敗 job 的 log 或 artifact。
2. 在本機跑對應命令重現。
3. 修改最小必要範圍。
4. 跑同一條本機命令確認修復。
5. commit 並 push。
6. 等 GitHub Actions 重新跑。

這個流程的好處是保留可追溯性。日後再看到同類失敗，可以從 commit history 與 CI log 找到當時的判讀方式。

發布 gate 路由

發布 gate 的責任是把「是否進入下一階段」變成明確條件。這一頁只處理失敗後的操作路由；required checks、job needs、environment protection 與 artifact handoff 的設計原理，獨立放在 CI gate 與 workflow 邊界。

常見處理情境

CI 失敗但本機通過時，優先檢查環境差異。常見差異包括語言版本、套件管理器版本、缺少子模組、缺少 build artifact、測試依賴未安裝、時區或檔案大小寫差異。這類問題要把版本與建置前置條件寫進 workflow、Makefile 或 script，讓重現條件成為專案的一部分。

測試不穩定時，優先把 Flaky Test 狀態標出來並建立 owner。短期可以隔離或重跑，長期要找到不穩定來源，例如等待條件錯誤、外部網路依賴、時間假設、測試資料不穩或動畫 transition 尚未完成。測試不穩定會降低 gate 信任度，因此它本身就是需要治理的 CI 問題。

Deploy 失敗但測試通過時，優先看 artifact 與權限。若 build output 存在且可下載，問題通常在部署通道、token permission 或 environment protection；若 artifact 缺失，就回到 build job。

反模式與替代做法

反模式的共同問題是讓 CI 失去判讀價值。CI 的目標是讓綠燈代表「這次變更在定義好的條件下可發布」。

最小可用流程

最小可用流程是讓每次變更都有同一條路徑。對小型靜態網站或個人 blog，先做到以下四件事，就能形成穩定發布節奏。

1. push 或 PR 觸發 lint / test / build。
2. production build 有單一入口。
3. 測試失敗時保留 artifact 或 report。
4. deploy 只接受測試與 build 通過後的產物。

這套流程建立後，CI 紅燈就會成為清楚的路由訊號：哪一層壞、用哪個命令重現、修完後用哪個 gate 放行。

若變更涉及後端服務，可再對照 backend 知識卡的 Runbook、Rollback Strategy 與 Release Gate 進一步細化故障處理順序與放行條件。

下一步路由

• 需要理解 CI 在可靠性模組的位置：讀 6.1 CI pipeline。
• 需要看靜態站部署案例：讀 本 blog 專案部署。
• 需要理解 CI gate 設計：讀 CI gate 與 workflow 邊界。
• 需要理解發布阻擋策略：讀 6.8 Release Gate 與變更節奏。

Workflow 總覽

本專案目前有五條 workflow。三條屬於 CI / CD 主流程，兩條屬於 Claude 協作輔助流程。

這張表的責任是提供入口。看到 GitHub Actions 紅燈時，先對照 workflow 名稱，把失敗歸到內容檢查、瀏覽器測試、部署或協作流程。

md-check

md-check 的責任是讓 content/ 裡的 Markdown 維持同一套結構契約。它會先用 Go build 出 scripts/mdtools，再依序執行 formatter 檢查、lint 與卡片連結檢查。

1name: md-check
2on:
3  push:
4    branches: [main]
5  pull_request:
6    branches: [main]

這條 workflow 的核心步驟是：

1. actions/checkout@v6
2. actions/setup-go@v6
3. go build -o ../../bin/mdtools
4. ./bin/mdtools fmt --check content/
5. ./bin/mdtools lint content/
6. ./bin/mdtools cards content/

md-check 失敗時，下一步是回本機跑同一組命令。fmt --check 失敗代表格式可由 fmt --fix 修正；lint 失敗代表標題、front matter、URL、code block 等結構契約不符；cards 失敗代表卡片連結、orphan 或 K4 規則需要修。

1./bin/mdtools fmt --check content/
2./bin/mdtools lint content/
3./bin/mdtools cards content/

維護這條 workflow 時，規則來源要和 Blog Markdown 寫作規範與 mdtools 檢查 對齊。改 scripts/mdtools/internal/rules/ 時，也要同步更新規範文章，避免 CI 行為和文件描述分叉。

Playwright tests

Playwright tests 的責任是驗證使用者可見行為。它會先建出完整 Hugo site 與 Pagefind index，再用 Chromium 驗證搜尋、版面與互動。

1name: Playwright tests
2on:
3  push:
4    branches: [main]
5  pull_request:
6    branches: [main]

這條 workflow 的核心步驟是：

1. checkout，並包含 submodules
2. 安裝 Hugo 0.148.2 extended
3. 安裝 Node 24
4. npm ci
5. npx playwright install --with-deps chromium
6. make site
7. npx playwright test
8. 失敗時上傳 playwright-report/

make site 是這條 workflow 的關鍵前置條件。它會產生 Hugo 靜態檔與三份 Pagefind index：pagefind、pagefind-title、pagefind-content。如果只跑 hugo --minify 就跑 Playwright，搜尋測試會因為缺少 index 而失敗。

Playwright 失敗時，下一步是下載 playwright-report 或讀 error context。若失敗發生在搜尋頁，先確認 make site 是否完整成功；若失敗發生在版面，先看 screenshot、bounding box 或 computed style；若失敗發生在互動，先看 selector 是否仍對準真實 DOM。

1make site
2npm test

維護這條 workflow 時，測試要守使用者行為，不應只守 implementation detail。像 TOC RWD 這類版面行為，可以用 viewport 測試固定桌面、筆電與手機三種狀態。

Deploy Hugo site to Pages

Deploy Hugo site to Pages 的責任是把 main 上的內容建置成 GitHub Pages artifact 並部署。它只在 push 到 main 時觸發，不在 pull request 上部署。

1name: Deploy Hugo site to Pages
2on:
3  push:
4    branches:
5      - main

這條 workflow 有兩個 job：

build job 會先跑 hugo --minify，並把輸出寫到 hugo-build-output.txt。目前它設了 continue-on-error: true，所以 Hugo build 失敗時會進入 Claude Debug 步驟，嘗試讓 Claude 分析錯誤並 commit 修復。

Fail if build was not fixed 是第二道保護。若原本 Hugo build 失敗，workflow 會重新跑一次 hugo --minify；如果 Claude 沒修好，這一步會讓 workflow 停止。

Pagefind index 會在 Hugo build 後產生：

1npx -y pagefind --site public --root-selector main
2npx -y pagefind --site public --root-selector "article.article-content > h1" --output-subdir pagefind-title
3npx -y pagefind --site public --root-selector ".article-body" --output-subdir pagefind-content

Deploy 失敗時，下一步先分層判讀。若 build job 失敗，回到 Hugo 或 Pagefind；若 Upload artifact 成功但 deploy job 失敗，檢查 Pages environment、permission、artifact 與 GitHub Pages 設定。

這條 workflow 目前的注意事項是：deploy workflow 自己沒有直接 needs md-check 或 Playwright tests，因為它們是獨立 workflow。這是本專案目前的實際邊界；gate 設計原理見 CI gate 與 workflow 邊界。

Claude Code

Claude Code 的責任是提供互動式 Claude 協作入口。它不會在每次 push 自動修程式，而是在 issue、comment 或 review 內容包含 @claude 時觸發。

1on:
2  issue_comment:
3    types: [created]
4  pull_request_review_comment:
5    types: [created]
6  issues:
7    types: [opened, assigned]
8  pull_request_review:
9    types: [submitted]

這條 workflow 的 gate 寫在 job if。只有以下情境會真正執行：

• issue comment 包含 @claude
• pull request review comment 包含 @claude
• pull request review body 包含 @claude
• issue title 或 body 包含 @claude

這條 workflow 給 Claude actions: read 權限，讓它能讀 PR 上的 CI 結果。這對「請 Claude 看 CI 為什麼失敗」很重要，因為 Claude 需要讀 workflow run、job log 或 check 結果才能判斷。

維護這條 workflow 時，重點是權限最小化。它目前給的是 contents: read、pull-requests: read、issues: read、id-token: write、actions: read，適合互動分析；若未來要讓 Claude 直接 commit，才需要重新評估寫入權限與保護條件。

Claude Code Review

Claude Code Review 的責任是在 PR 事件發生時跑 Claude code review。它和 Claude Code 不同，前者是 PR review automation，後者是被 @claude 叫起來的互動入口。

1on:
2  pull_request:
3    types: [opened, synchronize, ready_for_review, reopened]

這條 workflow 使用 code-review@claude-code-plugins，prompt 是：

1/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}

它的責任是提供 review 視角。Claude review 可以指出風險、邏輯問題或測試缺口；真正阻擋合併與發布的責任仍在 Required Checks、測試 workflow 與 deploy gate。

維護這條 workflow 時，可以依 PR 類型決定是否加 path filter。若未來只想在程式碼或 workflow 變更時觸發，可打開 paths 設定；若希望文章內容也被 review，就維持目前全 PR 觸發。

本專案的發布阻擋邊界

本 blog 的發布阻擋邊界需要同時看 YAML 與 GitHub repository 設定。這一節只記錄本專案目前能從 YAML 判讀出的事實；required checks、environment protection 與 artifact handoff 的原理不在本頁展開。

目前從 YAML 可直接確認的阻擋關係是：

若日後發現測試紅燈但 Pages 仍發布，本頁只負責指出目前 workflow 邊界；具體改法回到 CI gate 與 workflow 邊界 判斷，並對照 Required Checks 與 Environment Protection。

失敗時的維護路由

失敗時的維護路由要先定位 workflow，再定位 job，再回到本機重現。這能避免在錯誤層修錯問題。

這份路由也可以當維護 checklist。新增 workflow 時，至少要補三件事：觸發條件、失敗時看哪個 artifact 或 log、本機要用哪條命令重現。

本專案維護注意事項

本專案維護注意事項的責任是記錄和目前 YAML 直接相關的操作提醒。這些提醒隨 workflow 實作改變而更新，不承擔通用 CI 設計原理。

• Playwright tests 依賴 make site 產生 Pagefind index；搜尋測試失敗時先確認 production build 是否完整。
• deploy.yml 的 Hugo build 使用 continue-on-error: true，後面用 Claude Debug 與 retry build 接住失敗。
• Claude Code 目前是 read-oriented 互動入口；若未來要寫入 repo，需要重新審核 permission。
• .github/workflows/*.yml 有實作變更時，要同步更新本頁，讓維護入口維持可信。

下一步路由

• CI 紅燈處理流程：讀 CI 失敗到修復發布流程。
• CI gate 設計原理：讀 CI gate 與 workflow 邊界。
• CI 在可靠性模組的位置：讀 6.1 CI pipeline。
• 發布 gate 設計：讀 6.8 Release Gate 與變更節奏。
• Markdown 檢查規則：讀 Blog Markdown 寫作規範與 mdtools 檢查。

CI pipeline 的可靠性驗證在測試階段結束後，還需要兩道控制面才算完整。第一道是 deploy approval gate — 決定誰可以核准 production deploy、在什麼條件下放行。第二道是 credential 安全 — deploy 需要 cloud credential，但 long-lived secret 存在 CI 環境中會擴大洩漏面。

GitHub Actions 用 environment protection rules 處理第一道，用 OIDC federation 處理第二道。兩者搭配讓 deploy 流程同時滿足 6.8 release gate 的放行控制與 07 資安 的 credential 最小暴露原則。

Environment Protection Rules

Environment 是 GitHub Actions 的 deploy 分層單位。每個 environment（staging / canary / production）可以獨立設定 protection rules，讓不同風險等級的 deploy 走不同的放行流程。

Protection rule 類型

Required reviewers 是 deploy 層的 release gate。當 workflow job 標記 environment: production，GitHub 會暫停 job 直到指定 reviewer 核准。reviewer 的選擇應對齊服務 ownership — 由該服務的 on-call lead 或 tech lead 核准，避免核准權過於集中或分散。

Wait timer 提供一個緩衝窗口。deploy 前等待 N 分鐘讓團隊有時間檢查 staging 結果、確認沒有進行中的事故、或在發現問題時取消 deploy。timer 長度跟服務風險等級對齊 — 低風險服務可以 0 分鐘，交易路徑可以 15-30 分鐘。

Deployment branch policy 限制哪些 branch 可以觸發特定 environment 的 deploy。這防止 feature branch 意外 deploy 到 production。production 通常只接受 main 或 release branch。

分層建議

staging 用自動 deploy — push 到 staging branch 直接觸發 workflow，無需 approval，回饋速度最大化。production 用 required reviewer + wait timer — 確保每次 production deploy 都經過人工確認與緩衝。canary 介於兩者之間 — 可以自動 deploy 但加 wait timer，讓觀測指標有時間反映。

OIDC Cloud Auth

Long-lived credential 的風險

CI deploy 需要 cloud credential（AWS access key / GCP service account key / Azure service principal）。傳統做法是把這些 credential 存在 GitHub repository secret 或 environment secret 中。long-lived credential 的風險在於：洩漏後攻擊者可以長期使用、rotation 需要手動更新 CI 設定、credential scope 常設得比實際需求更大。

OIDC federation 的運作方式

GitHub Actions 支援作為 OIDC identity provider。workflow 在執行時可以向 GitHub 請求一個 short-lived OIDC token，cloud provider 信任這個 token 後發出 short-lived cloud credential。整個流程不需要在 CI 環境中存放任何 long-lived secret。

流程：workflow 啟動 → 向 GitHub OIDC provider 請求 token → token 帶有 repo / branch / environment 等 claim → cloud provider 的 trust policy 驗證 claim → 發出 short-lived credential（通常 1 小時有效期）。

Cloud provider 配置

AWS：在 IAM 設定 OIDC identity provider（issuer: token.actions.githubusercontent.com）、建立 IAM role 並設定 trust policy 限制 repo + branch + environment。workflow 中用 aws-actions/configure-aws-credentials action 取得 session credential。

GCP：設定 Workload Identity Federation pool + provider、建立 service account 並綁定 pool。workflow 中用 google-github-actions/auth action 取得 short-lived token。

Azure：在 Azure AD 設定 federated credential 給 app registration、限制 repo + branch + environment。workflow 中用 azure/login action。

Trust policy 的安全邊界

OIDC trust policy 必須限制到特定 repo、branch 與 environment。trust policy 寫成 wildcard（信任整個 GitHub org 的所有 repo）等於讓 org 內任何 repo 的 workflow 都能取得 cloud credential。最小權限原則：production environment 的 trust policy 只信任 repo:org/service:environment:production，不信任其他 environment 或 branch。

實作範例

 1# .github/workflows/deploy.yml
 2name: Deploy
 3on:
 4  push:
 5    branches: [main]
 6
 7permissions:
 8  id-token: write
 9  contents: read
10
11jobs:
12  deploy-staging:
13    runs-on: ubuntu-latest
14    environment: staging
15    steps:
16      - uses: actions/checkout@v4
17      - uses: aws-actions/configure-aws-credentials@v4
18        with:
19          role-to-assume: arn:aws:iam::123456789012:role/staging-deploy
20          aws-region: ap-northeast-1
21      - run: ./scripts/deploy.sh staging
22
23  deploy-production:
24    needs: deploy-staging
25    runs-on: ubuntu-latest
26    environment: production
27    steps:
28      - uses: actions/checkout@v4
29      - uses: aws-actions/configure-aws-credentials@v4
30        with:
31          role-to-assume: arn:aws:iam::123456789012:role/production-deploy
32          aws-region: ap-northeast-1
33      - run: ./scripts/deploy.sh production

staging job 自動觸發。production job 等 staging 完成後暫停，等待 environment protection rules 中設定的 reviewer 核准。兩個 job 各自用不同的 IAM role，scope 分離。

Environment secret 與 repository secret 的差異：environment secret 只在該 environment 的 job 中可用。把 production-only 的設定（如 database connection string）存在 production environment secret 而非 repository secret，避免 staging workflow 意外存取 production 資源。

邊界與陷阱

Environment protection rules 在 private repo 上需要 GitHub Team 或 Enterprise 方案。Free 方案的 private repo 無法使用 required reviewers 與 wait timer，只有 public repo 或付費方案可用。

OIDC trust policy 的常見錯誤是 subject claim 設定太寬。sub claim 的格式是 repo:{owner}/{repo}:environment:{name}（使用 environment 時）或 repo:{owner}/{repo}:ref:refs/heads/{branch}（不使用 environment 時）。用 wildcard match 或省略 environment 限制會讓非預期的 workflow 取得 credential。

Wait timer 設定要跟服務風險等級對齊。所有服務統一用 30 分鐘 wait timer 會拖慢低風險服務的 deploy velocity。對齊方式：低風險服務 0 分鐘、中風險 5-10 分鐘、高風險（交易路徑）15-30 分鐘。

Required reviewer 數量跟團隊大小對齊。只有 1 個 reviewer 等於沒有四眼原則；需要 5 個 reviewer 會造成 approval 排隊。2-3 個 reviewer 是多數團隊的平衡點。

整合路由

• 上游：6.1 CI pipeline（CI gate 通過後才進入 deploy 階段）
• 下游：6.8 release gate（environment protection 是 deploy 層的 release gate）
• 下游：6.23 verification evidence handoff（deploy 結果作為 release evidence）
• 平行：CircleCI contexts + approval jobs（同類功能的不同實作）
• 案例回寫：Microsoft 變更分層（變更風險分層對應 environment 分層）、Google Error Budget（error budget 消耗時提高 gate 門檻 → 可動態調整 required reviewer 數量）

Gate 形式

Gate 形式要依控制範圍選擇。PR 合併、job 執行順序、production 發布與 artifact 傳遞是四種不同責任，混在一起會讓紅燈的意義變模糊。

Required checks 適合保護主線。它讓測試結果成為合併條件，避免紅燈變更進入 main 或 release branch（backend 延伸見 CI Pipeline）。

Job needs 適合同一條 workflow 內的發布管線。它讓 deploy 必須等 test、build 或 package 成功後才執行，避免 deploy job 先於驗證結果流動（platform 延伸見 Deployment Contract）。

Environment protection 適合正式環境。即使 build 與測試通過，production 或其他目標環境仍可要求人工審核、特定分支或特定 reviewer 才能部署（治理延伸見 Release Gate）。

Artifact handoff 適合避免「測試一份、發布另一份」的漂移。較嚴謹的流程會讓 build job 產生 artifact，test job 驗證這份 artifact，deploy job 發布同一份 artifact（供應鏈延伸見 Artifact Provenance）。

Workflow 邊界

Workflow 邊界的責任是決定哪些步驟共享同一條執行圖。放在同一條 workflow 裡的 job 可以用 needs 建立顯式依賴；分散在不同 workflow 裡的流程，通常要靠 branch protection 或 environment protection 建立跨 workflow gate。

多 workflow 的關鍵風險是順序假設。GitHub Actions 的 workflow 彼此獨立；跨 workflow 順序需要靠 repository 設定或 API 顯式串接。

發布阻擋判讀

發布阻擋要同時看 YAML 與 GitHub repository 設定。YAML 說明 workflow 或 job 如何執行；跨 workflow 的「測試通過才發布」通常要靠 Branch Protection、required status checks 或 environment protection。

這個判讀順序能避免錯修。若測試紅燈但目標環境仍發布，問題通常在 deploy gate 尚未把測試狀態納入發布條件。

常見反模式

反模式的共同問題是讓 CI 綠燈與發布安全之間失去因果關係。CI 的目標是讓綠燈代表「這次變更在定義好的條件下可進下一階段」。

Tripwire

Tripwire 的責任是提示什麼時候 workflow 結構需要重切，讓團隊從局部 patch 回到 gate 設計。

• 測試紅燈仍發布：把 deploy gate 顯式化，使用 required checks 或同 workflow needs。
• 本機常常重現不出 CI：把命令收斂到 Makefile 或 npm scripts，減少 workflow 專屬命令。
• 測試常因 artifact 缺失失敗：建立 artifact handoff，讓測試與發布使用同一份產物。
• workflow 說明與實作分叉：同步更新 workflow 文件與 YAML，讓維護入口保持可信。

下一步路由

• CI 紅燈處理流程：讀 CI 失敗到修復發布流程。
• 靜態站部署案例：讀 本 blog 專案部署。
• 可靠性層的 release gate：讀 6.8 Release Gate 與變更節奏。

概念位置

Required Checks 位在 repository branch protection，連接 pull request 與 CI workflow 結果。

可觀察訊號

• PR 是否可合併取決於特定 checks 狀態。
• 團隊需要確保高風險變更不繞過驗證。
• CI workflow 增刪後需要同步調整合併條件。

接近真實服務的例子

專案可要求 md-check 與 Playwright tests 都通過才能合併 main。若只跑 workflow 但未設為 required，主線仍可能進入紅燈變更。

設計責任

Required Checks 要定義必要檢查集合、擁有者與變更流程，並和 workflow 命名保持一致。

三種服務管理方案

Process.start（直接啟動程序）

在 test 的 setUp 中用 Process.start 啟動服務程序，tearDown 中用 process.kill 停止。

適合的前提：服務是單一二進位檔（不需要 Docker），啟動速度快（< 2 秒），不需要持久化狀態。

app_tunnel 的 ttyd 就是這個模式。ttyd bash 一行指令啟動，不需要設定檔，不需要資料庫，啟動到可接受連線約 500ms。Test harness 只需要：

1setUp: process = Process.start('ttyd', ['--port', '7681', 'bash'])
2       await waitForPort(7681, timeout: 3s)
3tearDown: process.kill()

Docker Compose

用 Docker Compose 定義服務堆疊，CI 的 before_all 階段 docker compose up，after_all 階段 docker compose down。

適合的前提：服務有依賴（database + cache + app server）、需要特定 OS 環境、需要精確的版本控制。

Docker Compose 的成本是 image pull 時間（首次或 image 更新時）和容器啟動時間。CI 中可以用 image cache 減少 pull 時間，但冷啟動仍比直接啟動程序慢。

Testcontainers

在 test 程式碼中用 testcontainers 套件管理 Docker 容器。每個 test class 或 test suite 啟動自己的容器，test 結束後自動清理。

適合的前提：和 Docker Compose 類似，但需要更細粒度的控制（不同 test 用不同的服務設定），或需要在 test 程式碼中動態決定服務的啟動參數。

Testcontainers 的優勢是 test 和 fixture 在同一個程式碼檔案中，容易理解每個 test 需要什麼環境。缺點是每個 test suite 啟動自己的容器，比共用容器慢。

健康檢查

服務啟動後到可以接受請求之間有延遲。直接在啟動後發送 test request 會因為服務尚未 ready 而失敗。

健康檢查的方式依服務類型而定：

TCP port 可達：waitForPort(port, timeout) 反覆嘗試 TCP 連線，成功即表示服務在監聽。最簡單，適合所有 TCP 服務。

HTTP health endpoint：對 /health 或 /ready 發送 GET request，收到 200 表示服務 ready。比 port check 更可靠 — port 監聽不代表應用層 ready。

特定操作成功：執行一個輕量的業務操作（例如 WebSocket 連線 + 簡單指令），成功表示服務完全 ready。最可靠但最慢。

服務狀態隔離

不同 test 之間的服務狀態需要隔離 — test A 在服務中建立的資料不應該影響 test B。

三種隔離策略：

每 test 重啟服務：最強隔離，最慢。適合服務啟動快（< 1 秒）的場景。

每 test 重設狀態：服務持續運行，test 開始前清理狀態（truncate tables, flush cache）。適合服務啟動慢但重設快的場景。

每 test 用獨立 namespace：服務持續運行，每個 test 使用獨立的 database schema / topic / channel。適合支援多租戶的服務。

app_tunnel 的 ttyd 是無狀態服務（每次連線是獨立的 terminal session），不需要狀態隔離。每個 test 建立新的 WebSocket 連線 = 新的 session。

下一步路由

• 什麼時候值得建 protocol integration test 基礎設施 → 成本判斷表
• Protocol integration test 的定義 → Protocol integration test 定義
• WebSocket 的 protocol test 實作 → WebSocket 協議測試實作

四類根因

計時依賴

Test 依賴特定的時間條件 — timeout、delay、animation duration。系統負載不同時，時間條件可能滿足也可能不滿足。

常見模式：

• await Future.delayed(Duration(seconds: 2)) + assertion — 如果操作在 2 秒內完成，test 通過；如果 CI 機器負載高導致操作超過 2 秒，test 失敗
• expect(stopwatch.elapsed, lessThan(Duration(seconds: 1))) — 效能斷言在不同機器上結果不同

處理策略：用事件驅動代替 timeout。等待 stream.first 代替 delay(2s) + check；用 completion signal 代替固定等待時間。如果必須用 timeout，設定寬裕的上限（10x 預期時間）而非精確的預期值。

環境差異

Test 在不同環境下行為不同 — 作業系統、檔案系統、時區、locale、DNS 解析。

常見模式：

• 檔案路徑分隔符（/ vs \）在不同 OS 下不同
• 時間格式化結果依時區而定（UTC vs local）
• 浮點數比較因 CPU 架構不同有微小差異

處理策略：用 path.join 代替硬編碼路徑；時間操作用 UTC；浮點比較用 closeTo 代替精確比較。在 CI 中固定環境變數（TZ=UTC、LANG=en_US.UTF-8）。

資源競爭

Test 依賴共享資源（port、暫存檔、資料庫行）— 平行執行時多個 test 同時存取同一資源，結果依賴執行順序。

常見模式：

• 多個 test 監聽同一個 port — 第二個綁定失敗
• 多個 test 寫入同一個暫存檔 — 內容被覆蓋
• 多個 test 操作同一個資料庫 table — 資料互相干擾

處理策略：每個 test 使用獨立的資源（隨機 port、唯一檔名、隔離的資料庫 schema）。如果資源無法隔離，sequential 執行相關 test（@sequential 標註）。

非確定性輸出

程式碼的輸出本身不確定 — Set 的迭代順序、Map 的 key 順序、非同步操作的完成順序。

常見模式：

• 斷言 Set 的 toString() 結果等於特定字串 — Set 的迭代順序不保證
• 斷言 Future.wait([a, b]).then((results) => results[0]) — a 和 b 的完成順序不固定
• 斷言 JSON 序列化的 key 順序 — Map 的 key 順序在不同實作中不同

處理策略：不斷言順序（用 containsAll 代替 equals 比較集合）；不斷言序列化格式（反序列化後比較值）；用 completion matcher 代替順序假設。

診斷步驟

發現疑似 flaky test 時的診斷步驟：

1. 確認 flaky：在乾淨環境連續跑 20 次，確認失敗是隨機的（如果每次都失敗，是 bug 不是 flaky）
2. 收集失敗訊息：記錄每次失敗的 assertion 訊息、stack trace、環境資訊（OS 版本、CI 機器 ID）
3. 分類：失敗訊息指向時間（timeout）→ 計時依賴；指向值不同 → 非確定性或環境差異；指向連接失敗 → 資源競爭
4. 修復：根據分類使用對應的處理策略

分類和修復之外，flaky test 的根因有時來自 assertion 本身的設計 — Assertion 品質三問提供判斷 assertion 是否有效的框架。如果 flaky 的根因是 mock 和真實服務的行為差異，回到 Mock 邊界判斷決策表判斷 mock 是否還適用。Protocol integration test 在 CI 中的服務 fixture 管理也是 flaky 的常見來源 — 服務啟動不完全就開始跑 test。

概念位置

Artifact 位在 build、test、package、deploy 之間，常見形式包含靜態網站檔案、container image、app bundle、安裝包與報告檔案。

可觀察訊號

• 測試與部署的輸入來源需要一致。
• 發布事故需要從線上版本反查 build run。
• 團隊需要管理產物保留時間與完整性驗證。

接近真實服務的例子

前端靜態站會把 public/ 作為 artifact，上傳後再部署。後端則用 image digest 作為 artifact 識別，推進到不同環境。

設計責任

Artifact 要定義命名、版本追溯、保留策略與完整性檢查，讓發布結果可重播、可比對、可審計。

概念位置

Artifact Handoff 位在 build、test、deploy 之間，透過 upload / download artifact 串接驗證與發布。

可觀察訊號

• 測試通過但部署後行為與測試結果不一致。
• 多環境重新 build 造成版本漂移。
• 事故追查時缺少從部署版本反查 build run 的路徑。

接近真實服務的例子

CI build 產生靜態網站 artifact，browser test 驗證該 artifact，deploy job 再發布同一份產物。容器場域則可把 image digest 當成 handoff 物件。

設計責任

Artifact Handoff 要定義產物格式、保留策略、完整性驗證與追溯欄位，讓測試結果可直接映射到發布結果。

概念位置

Preview Environment 位在 pull request workflow 與正式部署流程之間，常由臨時 URL、隔離資源與到期清理組成。

可觀察訊號

• 團隊需要在合併前驗證 UI、路由或互動行為。
• 單靠測試報告不足以判斷體驗差異。
• 變更常包含環境變數、CDN 設定或靜態資產路徑。

接近真實服務的例子

前端 PR 自動建 preview URL 給 reviewer 驗證。後端則可能建立 review app 供 API 與整合測試使用。

設計責任

Preview Environment 要定義建立條件、資源上限、可見範圍與清理策略，避免成本與風險失控。

概念位置

Migration 位在 build 之後、deploy 與 rollout 之前後的關鍵路徑，常與 release gate、rollback strategy 一起設計。

可觀察訊號

• 新舊版本需要共存一段時間。
• 發布步驟包含 schema 或資料形狀變更。
• 部署失敗時要判斷是否可回退或需要 forward fix。

接近真實服務的例子

後端服務先擴充 schema，再讓新版本寫入新欄位，最後收斂舊欄位讀取；整個過程需要 migration gate 與回退方案。

設計責任

Migration 要定義相容策略、執行順序、觀測指標與異常回復路由，避免部署成功但資料邏輯失效。

場域定位

前端部署和後端部署的差異在於 runtime 責任位置。前端產物通常在 build time 完成大部分工作，發布後由 browser、CDN 或 static hosting 提供服務；後端服務則要在 runtime 處理連線、資料庫、migration、狀態與 rollback。

Build 階段負責產生 browser 實際會執行的內容。真實服務常見訊號是 bundle size、asset hash、base URL、環境變數與 static route 是否穩定；若 build 只能在開發機成功，CI 就要把 Node 版本、package lock、build command 與環境變數收斂成固定入口。

Test 階段負責驗證使用者可見行為。前端常見測試包含 component test、browser regression、accessibility check 與 layout check；測試應盡量靠近 production artifact，讓 dev server 的寬鬆行為不會蓋掉實際部署問題。

Artifact 階段負責保存可發布產物。靜態檔、搜尋索引與 sourcemap 都可能影響使用者體驗與除錯能力；測試與發布共用同一份 artifact，可以避免「測試通過的是 A，發布出去的是 B」的漂移。

Deploy 階段負責把 artifact 放到 hosting 或 CDN。真實風險通常集中在 HTML cache、asset cache、SPA fallback、preview URL 與 production domain 是否對齊。

Rollback Strategy 階段負責讓上一個可用 artifact 能重新服務使用者。前端 rollback 通常比後端快，但若 build time 環境變數、資料 schema 或 CDN cache 已變更，回退仍需要驗證頁面路由與 API 相容性。

常見注意事項

• CDN cache 要和 asset hash、HTML cache policy 分開看。
• Preview environment 要能對應 PR，讓 reviewer 看到真實 build。
• 前端測試要跑在 production-like artifact 上，避免 dev server 行為遮蔽問題。
• 環境變數若在 build time 注入，重新發布才會生效。
• SPA route 需要 fallback 設定，靜態站 route 需要檔案路徑與 base URL 對齊。

學習路線

下一步路由

• 前端 artifact 流程：讀 前端 artifact 與 preview deployment 流程。
• 本 blog 的靜態站案例：讀 本 blog 專案部署。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。

概念位置

Branch Protection 位在 pull request 與主線分支之間，屬於 CI workflow 之外的治理層。

可觀察訊號

• 主線偶爾進入未驗證變更。
• workflow 已存在但合併條件未綁定。
• 團隊需要統一 reviewer 與狀態檢查門檻。

接近真實服務的例子

專案要求 md-check 與 Playwright tests 必須綠燈，且至少一位 reviewer 批准才可合併 main。

設計責任

Branch Protection 要定義必要 checks、審查規則與例外流程，並和 workflow 命名同步維護。

場域定位

後端部署的主要風險來自有狀態依賴與長時間執行。API、worker、scheduler 與 consumer 會連到資料庫、queue、cache 與第三方服務；部署流程需要確認程式、資料與流量切換順序。

Build 階段負責產生可部署服務。後端 build 常見形式是 binary、package 或 container image；判讀重點是版本是否能追到 commit、依賴是否固定、產物是否能在乾淨環境重建。

Test 階段負責驗證服務契約。單元測試只能覆蓋局部邏輯，integration、contract 與 migration 測試才會揭露資料庫、queue、cache 與外部服務之間的相容性風險。

Migration 階段負責推進資料結構與資料狀態。真實服務要支援新舊程式短暫共存，因此 migration 應偏向可漸進、可重試、可觀測，必要時用 forward fix 取代直接回滾資料。

Rollout Strategy 階段負責把流量安全導向新版本。Rolling、canary 與 blue-green 都需要可靠的 health、readiness、metrics 與 log；若 readiness 只檢查 process alive，流量仍可能被送到尚未準備好的服務。

Rollback Strategy 階段負責在新版本失效時縮小影響範圍。後端 rollback 要同時考慮程式、資料、queue message、外部 side effect 與 config；只回退 image tag，通常不足以處理已寫入的資料變化。

常見注意事項

• Migration 要和 app rollout 分開設計，避免新舊版本不相容。
• Health check 只代表 process alive，readiness 才能判斷能否接流量。
• Worker / consumer 部署要考慮重複處理、idempotency 與 consumer lag。
• Config rollout 需要版本化與回退路徑（深入見 Config Rollout）。
• Rollback 不只回程式，也要處理資料與外部副作用（深入見 Rollback Strategy）。

學習路線

下一步路由

• 後端發布主流程：讀 後端 migration、rollout 與 rollback 流程。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• Backend reliability：讀 模組六：可靠性驗證流程。
• Release gate：讀 6.8 Release Gate 與變更節奏。

本文是跨 vendor migration playbook、cross-link Jenkins 跟 GitHub Actions。跑 migration-playbook-methodology 6 維 audit 後對映 Schema = High（Groovy DSL ↔ YAML workflow）→ Type A phased translation。

Pipeline 5 段 lifecycle 的對位 + 翻譯

本文按 pipeline lifecycle 5 段 組織內容（variant E）— 不是「為什麼遷」driver 開頭，是 Jenkins vs GHA 對 5 段各自的處理：

跑 6 維 diff dimension audit：

Schema = High（其他 Medium-Low）→ Type A phased translation 為主、加 paradigm + operational 獨立段。

為什麼遷：cost / vendor / cloud-native 三條 driver

• Cost：Jenkins self-hosted 是「免費 software + 高 ops cost」、GHA 按 minute 計費對中小團隊更便宜
• Vendor consolidation：repository 已在 GitHub、整合進 GHA 省一個外部系統
• Cloud-native：GHA matrix build + reusable workflow 對 cloud-native deploy（K8s / serverless）有 first-class action

Phase 0：Audit + classify

 1# Jenkins workspace 盤點
 2find . -name "Jenkinsfile" -o -name "*.groovy"
 3# 列所有 pipeline file
 4
 5# 統計 plugin 使用
 6# Jenkinsfile 內 import / @Library / sh "tool plugin..."
 7grep -rE "@Library|import|tools\s*\{" Jenkinsfile*
 8
 9# 每 pipeline 評估 complexity
10# - Simple linear pipeline: 1-3 stage、無 shared library
11# - Medium: parallel stage + 2-5 shared library
12# - Complex: 條件分支 + 動態 stage + 10+ plugin / 5+ shared library

Audit output：

• 列「100 個 pipeline、35 simple / 50 medium / 15 complex」
• 每 complexity level 估翻譯時間（simple 0.5 day / medium 2 day / complex 5-10 day）
• Plugin 依賴清單對應 GHA action 替代品

Phase 1：Schema 對位（Groovy DSL ↔ YAML）

 1// Jenkins Declarative Pipeline
 2pipeline {
 3  agent { label 'docker-build' }
 4  stages {
 5    stage('Test') {
 6      parallel {
 7        stage('Unit') { steps { sh 'mvn test' } }
 8        stage('Integration') { steps { sh 'mvn verify' } }
 9      }
10    }
11  }
12  post {
13    failure { mail to: 'devops@', subject: 'Build failed' }
14  }
15}

 1# GHA Workflow 對等
 2name: CI
 3on: [push]
 4jobs:
 5  test:
 6    runs-on: [self-hosted, docker-build]
 7    strategy:
 8      matrix:
 9        suite: [unit, integration]
10    steps:
11      - uses: actions/checkout@v4
12      - name: Run ${{ matrix.suite }}
13        run: |
14          case "${{ matrix.suite }}" in
15            unit) mvn test ;;
16            integration) mvn verify ;;
17          esac
18  notify-failure:
19    needs: test
20    if: failure()
21    runs-on: ubuntu-latest
22    steps:
23      - uses: dawidd6/action-send-mail@v3
24        with:
25          to: devops@
26          subject: Build failed

對位差異：

• parallel { ... } → strategy.matrix（粒度不同、matrix 是「同 step 不同參數」、parallel 是「不同 step」）
• post.failure → 獨立 job + if: failure()
• @Library shared library → reusable workflow（uses: ./.github/workflows/reusable.yml）
• Jenkins tools { jdk 'java17' } → setup-java action（手動配 toolchain）

Phase 2：Translation pipeline（3-tier hybrid）

對應 Splunk → Elastic translation 同 3-tier：

• Tier 1：community tool（jenkins-to-actions converter、cover 簡單 pipeline 30-50%）
• Tier 2：LLM-assisted（Claude / GPT 翻 medium complexity、人工 verify）
• Tier 3：manual（shared library 改 reusable workflow / conditional 動態 stage 重寫）

Phase 3：Parallel run（雙 CI 跑 4-8 週）

1Repository ──┬─→ Jenkins webhook ──→ Jenkinsfile pipeline
2             └─→ GitHub Action ────→ .github/workflows/ci.yml
3
4Compare:
5- 同 commit 兩端結果一致
6- Latency / cost / artifact location 對齊

Diff dashboard 列「test pass rate / build time / failure mode」三 metric、跑到 95%+ 一致才進 cutover。

Phase 4：Cutover + cleanup

• Disable Jenkins webhook
• GHA 成 primary CI
• Jenkins 留 standby 2 週 fallback
• Decommission Jenkins controller + agents

Production 故障演練

Case 1：Shared library equivalence、reusable workflow 表達不足

徵兆：複雜 Jenkins shared library（含 Groovy class / closure / 動態變數）翻成 reusable workflow 後失準、某些動態邏輯無法表達。

根因：Jenkins Groovy 是 imperative + 完整 programming language；GHA reusable workflow 是 declarative YAML、limited expressiveness。

修法：

1. 複雜邏輯外包到 script：reusable workflow 只當 orchestrator、複雜邏輯放 .github/scripts/*.sh 或 actions/javascript-action
2. 自定 composite action：multi-step logic 包進 composite action、reuse 程度比 reusable workflow 高
3. 退役過度設計的 shared library：trans 過程暴露 90% library code 其實只用 10%

Case 2：Ephemeral workspace、build cache 失敗

徵兆：cutover 後 build time 從 5 分鐘漲到 20 分鐘；Maven / Gradle / node_modules / Docker layer 每次都重抓。

根因：Jenkins agent workspace persistent、build cache 跨 build 保留；GHA ephemeral runner 每次新 VM、cache 預設沒帶。

修法：

1. actions/cache@v4：cache key 用 hashFiles('**/pom.xml') 等 lock file、cross-build 復用
2. Self-hosted runner with cache：critical pipeline 跑 self-hosted runner、persistent volume
3. Docker layer cache：用 docker/build-push-action 配 BuildKit cache、不 rebuild full image

Case 3：Plugin 不對等、CI feature 退化

徵兆：Jenkins 用 50+ plugin、GHA action marketplace 找不到對應；team 對 SonarQube quality gate / Jira integration / custom report 等失去 first-class 支援。

根因：Jenkins plugin ecosystem 20+ 年累積、GHA marketplace 5 年；某些 niche plugin 在 GHA 沒對等 action。

修法：

1. API-based integration：用 curl 對 vendor API 直接 call、不依賴 plugin / action
2. 自寫 action：critical feature 自寫 composite / JavaScript action、publish 到 marketplace
3. 退役舊 plugin：trans 期間 audit plugin 真實使用、80% 可退役

Case 4：Self-hosted runner setup + scaling

徵兆：production workload 需要 GPU / large memory runner；GHA hosted runner spec 不夠、想用 self-hosted runner、發現 scaling / security / monitoring 比 Jenkins agent 複雜。

根因：GHA self-hosted runner 是 ephemeral、scaling 需要 runner controller（actions-runner-controller on K8s）；跟 Jenkins agent / Kubernetes plugin 對應但 setup 不同。

修法：

1. actions-runner-controller (ARC)：K8s-native runner scaling、跟 Jenkins K8s plugin 對應
2. Runner labels：用 label 路由 job（runs-on: [self-hosted, gpu, linux]）
3. Security：ephemeral runner 用 short-lived token、不跨 job persist secret

Case 5：Matrix build vs parallel stage 表達差

徵兆：Jenkins 有 動態 parallel（runtime 決定要跑哪些 stage、按 input 變動）；GHA matrix 是 static at workflow load time、表達不到。

根因：GHA matrix 是 declarative、workflow parse 時 expand；runtime 動態決定 stage 需要用 if: condition + 多 job。

修法：

1. 動態 matrix：用 jobs.set-matrix 先跑一個 job 算 matrix、輸出 JSON、後續 job strategy.matrix: ${{ needs.set-matrix.outputs.matrix }}
2. conditional job：每個 dynamic stage 寫獨立 job + if: 控制觸發
3. 重設計：90% 動態邏輯其實可改 static matrix + condition、純 runtime 動態通常是 over-engineering

Capacity / cost

判讀：100+ pipeline organization 切 GHA 通常 6-12 月 ROI 持平、之後省 ops cost；< 30 pipeline 早就該切。

整合 / 下一步

跟 GitLab CI 對位

GitLab CI YAML 語法跟 GHA 接近、shared library 對應 include:、self-hosted runner 對等；Jenkins → GitLab CI migration 流程跟本文鏡像對稱、3-tier translation pipeline 通用。

跟 Circle CI 對位

CircleCI orb 對等 GHA composite action；跨 SaaS CI 切換比 Jenkins → GHA 簡單（都 YAML-based）。

反向 migration（GHA → Jenkins）

少數 enterprise（金融 / 政府）合規要求 self-hosted CI / on-prem；GHA → Jenkins 鏡像對稱、注意 Jenkins shared library 表達力更強、reusable workflow 內 dynamic 邏輯可不必拆。

下一步議題

• Reusable workflow + composite action 混用：reusable workflow 適合 跨 repo orchestration、composite action 適合 單 repo logic encapsulation
• OIDC + cloud deploy：用 OIDC token 取代 long-lived cloud credential、是 GHA migration 順便升級的機會
• Cost optimization：minute-based billing 對 high-volume CI 需要 monitoring + budget alert

相關連結

• Target vendor：GitHub Actions
• 平行 vendor：CircleCI
• 平行 migration playbook（Type A）：Splunk → Elastic Security / MySQL → PostgreSQL
• Methodology：Migration playbook methodology

場域定位

App 部署的風險集中在 artifact 不可變、簽章憑證、store review 與版本分佈。後端可以快速 rollback，前端靜態站可以重新部署，但已安裝的 App 需要靠更新、feature flag 或服務端相容性管理。

Build 階段負責產生可安裝 artifact。Mobile 常見產物是 IPA、APK 或 AAB，desktop 則可能是 installer 或 signed package；版本號、build number 與 commit 對應關係會決定後續除錯與回報能否追溯。

Signing 階段負責證明 artifact 由可信來源發布。憑證、profile、keystore 與 signing secret 都屬於發布能力；它們需要輪替、權限控管與備援流程，避免單一憑證問題中斷發布（安全治理延伸見 Secret Management）。

Test 階段負責驗證不同裝置與作業系統組合。App 測試常見風險是 emulator 通過但真機失敗、特定 OS 權限模型不同、背景執行限制不同；device matrix 要依使用者分佈與高風險功能選擇。

Release 階段負責把 artifact 送進發行通道。Store review、phased rollout、internal testing、beta track 與 production track 都是 gate；發布節奏要把審核時間與分批比例納入 rollout strategy 的風險控制（backend 延伸見 Config Rollout）。

Rollback Strategy 階段負責處理已安裝版本。App 發布後會長期存在多個使用者版本，因此 hotfix、remote config、kill switch 與後端相容性要一起設計（相容治理延伸見 API Contract）。

常見注意事項

• 簽章憑證是發布能力的一部分，要用 Secret Management 管理。
• 版本號與 build number 要可追溯到 commit 與 artifact。
• Store review 會讓 rollback 和 hotfix 變慢，風險要提前用 feature flag 控制。
• Client / server contract 要支援多版本共存。
• Crash reporting 與 phased rollout 是發布後 gate 的一部分。

學習路線

下一步路由

• App 發布主流程：讀 App 簽章、商店審核與分批發布流程。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。

場域定位

Image 部署常出現在後端、worker、batch job 與自架服務。它把「在哪個環境跑」前移到 build 階段，但也引入 registry、tag、base image、vulnerability scan、SBOM 與 promotion 流程（platform 概念可對照 Container）。

Build 階段負責把 application 與 runtime 封裝成 image。Multi-stage build、dependency cache、base image 與 layer 順序會影響速度、安全性與可重現性；CI 應能從 Dockerfile 與 lockfile 重建同一類產物。

Tag 階段負責讓 image 可追溯。Commit SHA、release tag 與 semver 各自服務不同查詢情境；production 需要能從 running image 反查 source、workflow run 與掃描結果。

Scan 階段負責讓 image 風險可見。Vulnerability scan、secret scan 與 SBOM 能把 base image、OS package 與 dependency 風險顯性化；阻擋門檻要和例外流程一起定義，讓掃描結果能被分流處理。

Registry 階段負責保存與推進 image。真實流程通常需要 retention、immutability、promotion 與權限控管；production image 應來自已驗證 artifact handoff，讓各環境推進同一份產物（供應鏈治理可對照 Artifact Provenance）。

Runtime 階段負責把 image 轉成可運行服務。Kubernetes、Compose、ECS 或其他平台都需要 health check、readiness、resource limit、secret injection（可對照 Secret Management）與 rollback 設計，否則 image 成功不等於服務可用。

常見注意事項

• latest 不適合當 production 追溯依據。
• Base image 要有更新節奏，否則掃描結果會持續惡化。
• Build secret 不應留在 image layer。
• Scan gate 要區分阻擋門檻與可接受例外。
• Promotion 應推進同一份 image，讓 staging 與 production 的差異集中在設定與流量。

學習路線

下一步路由

• Image 供應鏈流程：讀 Image build、scan、registry 與 promotion 流程。
• 後端部署：讀 後端部署 CI/CD。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• Backend deployment platform：讀 模組五：部署平台與網路入口。

場域定位

Serverless 發布通常以函式版本為單位，並透過 Function Alias 或流量權重切換。部署步驟看起來短，但對權限、Event Source、重試政策與 observability 欄位要求很高。

常見注意事項

• 部署前要先驗證 runtime 與依賴版本，避免 deploy 成功但 invocation 失敗。
• 事件觸發型函式要明確設定 retry、dead-letter 或回放策略。
• 權限設定要收斂到最小範圍，避免函式擴權風險。
• 冷啟動與併發上限要納入發布後觀測指標。

學習路線

下一步路由

• Serverless 發布主流程：讀 Serverless function 版本、事件來源與回復流程。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。
• Backend 相關概念：讀 Serverless / worker 相關知識卡。

場域定位

Data pipeline 常包含 batch job、stream processor、dbt model 或 workflow scheduler。部署判斷不只看程式可執行，還要看資料是否可追溯、可對帳、可修復。

常見注意事項

• schema 變更要先定義相容窗口，再切換 downstream。
• Backfill 要有節流與 Checkpoint，避免壓垮上游與儲存層。
• 部署後需比對新舊輸出一致性，建立 correctness check。
• 重跑流程要有 runbook，避免人工臨場判斷失誤。

學習路線

下一步路由

• Data pipeline 發布主流程：讀 Data pipeline backfill、checkpoint 與 rerun 流程。
• 後端資料遷移概念：讀 Migration。
• 資料修補與比對：讀 Backfill 與 Correctness Check。
• Gate 原理：讀 CI gate 與 workflow 邊界。

概念位置

Flaky Test 位在 test stage 與 release gate 之間，會放大重跑成本與判讀延遲。

可觀察訊號

• 同一 commit 重跑結果時好時壞。
• 失敗集中在等待條件、時間假設或外部依賴。
• 團隊習慣以重跑代替根因修復。

接近真實服務的例子

UI 測試在動畫未完成時抓取元素，或整合測試依賴不穩定第三方 API，都容易出現 flaky pattern。

設計責任

Flaky Test 治理要建立 owner、隔離策略、修復 SLA 與觀測指標，讓測試結果恢復可判讀性。

概念位置

Backfill 位在資料 schema、transform logic 或歷史資料修補之後，常出現在 data pipeline、database migration、search index rebuild 與 feature store 更新。

可觀察訊號

• 新欄位需要從既有資料補值。
• 歷史 partition 需要用新版邏輯重新計算。
• 補算任務需要節流、停損與對帳。

接近真實服務的例子

訂單報表新增 net_revenue 欄位時，pipeline 先讓新資料寫入新欄位，再分批 backfill 過去 12 個月的 partition，並用 row count 與金額總和比對結果。

設計責任

Backfill 要定義補算範圍、批次大小、checkpoint、停損條件與對帳方式，讓歷史資料修補成為可停止、可接續、可驗證的流程。

場域定位

IaC 流程通常分成 plan、review、apply 三段，並依環境分層推進。部署成功不只代表指令完成，還代表資源狀態符合預期且未引入漂移。

常見注意事項

• plan 與 apply 要用同一份輸入與版本，避免結果漂移。
• state backend 要有鎖定與權限隔離，避免併發覆寫。
• 高風險資源變更需要額外 gate（人工審核或變更時窗）。
• Infrastructure Drift 偵測要定期執行，並有修復責任人。

學習路線

下一步路由

• IaC 發布主流程：讀 IaC plan、apply、drift 與 recovery 流程。
• 環境保護：讀 Environment Protection。
• 部署合約：讀 Deployment Contract。
• 變更放行：讀 Release Gate。

概念位置

Checkpoint 位在長時間 job、stream processor、batch pipeline 與 migration 任務之間，常以 partition、offset、run id、cursor 或 processed marker 呈現。

可觀察訊號

• 任務執行時間長，失敗後需要接續。
• 重跑同一區間可能造成重複寫入。
• streaming consumer 需要保存 offset 或 event position。

接近真實服務的例子

資料回填每次處理一個日期 partition，完成後寫入 backfill_runs 表。任務中斷時，下一次從最後成功 partition 的下一段開始。

設計責任

Checkpoint 要定義進度格式、提交時機、失敗恢復、重跑覆寫與觀測欄位，讓長時間任務具備可恢復性。

場域定位

Desktop client 常見於 Flutter Desktop、Electron、Tauri。部署流程通常要分平台建置（macOS、Windows、Linux），並處理安裝體驗、Release Channel 更新節奏與版本共存。

常見注意事項

• 不同 OS 的簽章與公證流程需分開治理。
• Auto-update 要有版本相容策略與 fallback feed。
• 崩潰回報與更新成功率應列為發布後 gate。
• 若與 Flutter App 共用程式碼，要明確區分 mobile 與 desktop 的發布管線。

學習路線

下一步路由

• Desktop 發布主流程：讀 Desktop client 簽章、公證與自動更新流程。
• 行動與客戶端通用觀念：讀 App 部署 CI/CD。
• 簽章治理：讀 App Signing 與 Secret Management。
• 失敗處理：讀 CI 失敗到修復發布流程。

概念位置

Rerun 位在測試失敗、部署預演失敗、資料任務失敗或 pipeline repair 之後，負責判斷重新執行是否會改變輸出或擴大副作用。

可觀察訊號

• 同一 commit 的測試結果前後不一致。
• 資料任務部分成功、部分失敗。
• 部署 dry run 失敗後需要確認是否可安全再跑。

接近真實服務的例子

每日營收 pipeline 第三個 partition 寫入失敗。團隊先確認前兩個 partition 已完成且輸出可覆寫，再指定 run id 與 partition 範圍 rerun，避免重複計算全部歷史資料。

設計責任

Rerun 要定義可重跑條件、輸出覆寫規則、idempotency、觀測結果與人工審核門檻，讓「再跑一次」成為受控恢復策略。

場域定位

套件發佈常見於 NPM、PyPI、Maven、Crates 等生態。發布後會被多個下游專案依賴，因此每次 release 都是公共契約變更。

Release 發布類型分類

「發版」在中文討論裡常被當成單一動作，但實際上有五條互不重疊的通道，每條的觸發條件、產物形式、下游取用方式都不一樣。下游使用者讀 README 時若沒分清楚自己在走哪條通道，很容易踩到「文件寫了安裝指令，但對應通道還沒被建立」的情況。

這五類常常組合出現（例如同時推 source、registry、binary release）。組合愈多、上游維護成本愈高，但下游能用的入口也愈廣。判讀訊號：

• README 寫的是 pip install x → 屬 registry，去 PyPI 確認版本
• README 寫的是 curl ... /releases/latest/download/...sh | sh → 屬 binary release + installer，去 GitHub Releases 確認 asset 存在
• README 寫的是 git clone 後 make → 只走 source，沒任何打包通道
• README 寫的是 docker pull ghcr.io/... → 屬 container image，去 registry 確認 tag

常見注意事項

• 發版前要明確區分 breaking / feature / fix，避免版本語意錯置。
• 發版流程應固定化（tag 規則、changelog 來源、artifact provenance）。
• 對外 SDK 要維持 contract 測試，避免下游升級破壞。
• 套件來源與 token 權限要最小化，並定期輪替。
• README 安裝段落寫的通道，發版前要實際跑過一次 — 「workflow 寫好」不代表「通道已上線」。

安裝路徑分層

Package release 的文件建議同時提供兩條安裝路徑，讓不同風險場景有對應入口。

這個分層能避免單一路徑綁死全部使用者。上游維護者要確保兩條路徑都可用，且文件清楚標示使用時機。可審計路徑的具體範例可直接沿用 Binary release 與 installer 模式 的最小安全基線。

學習路線

下一步路由

• 想理解 binary release + installer 模式（curl … | sh）：讀 Binary release 與 installer 模式。
• 供應鏈與產物可信度：讀 Artifact Provenance。
• 版本契約：讀 API Contract 與 Contract。
• 失敗處理：讀 CI 失敗到修復發布流程。

專案定位

本專案的部署產物是靜態網站。Hugo 負責產生 HTML，Pagefind 負責產生搜尋索引，GitHub Pages 負責 hosting，Playwright 負責驗證搜尋與版面行為。

與通用 CI/CD 的關係

本資料夾是實例層。通用 gate 原理、不同部署場域差異與失敗處理流程放在上層文章；本資料夾只回答「這個 blog 專案現在怎麼部署、失敗時要看哪裡」。術語定義統一回連 CI 知識卡片。

下一步路由

• 本專案 workflow：讀 GitHub Actions workflow。
• 前端部署通用注意事項：讀 前端部署 CI/CD。
• CI gate 原理：讀 CI gate 與 workflow 邊界。
• Markdown CI 規則：讀 Blog Markdown 寫作規範與 mdtools 檢查。

概念定位

Artifact 是 CI/CD 流程中的交付單位。前端可能是 dist/，後端可能是 binary 或 image，App 可能是 IPA / AAB，資料任務可能是 DAG 或 query package；不同形式的 artifact 都承擔同一個責任：把 source change 轉成可驗證、可保存、可推進的產物。

Build once 的責任是降低環境漂移。若 test job 與 deploy job 各自 build，一個 lockfile、環境變數或 base image 差異就能讓兩份產物不同；此時 CI 綠燈不再能證明 production 內容可信。

Verify once 的責任是把測試結果綁到具體產物。測試應輸出 artifact identity，例如 checksum、Image Digest、release asset name 或 bundle version，讓 reviewer 能確認紅綠燈對應哪份內容。

Artifact handoff 的責任是在 job 邊界保留身分。Upload / download artifact、registry digest、release asset、package registry 與 object storage 都可以做 handoff；重點是交接時沿用既有產物。

Promote same artifact 的責任是讓環境差異集中在設定與流量。Staging 驗證過的 image、package 或 static artifact 應被推進到 production；若 production 重新 build，就需要重新驗證 production 那份產物。

Recover artifact 的責任是讓 rollback 有實體目標。沒有保留 artifact 的 rollback 會變成「從舊 commit 重新 build」，這會受到依賴、base image、registry、toolchain 與時間漂移影響。

可重播性檢查

可重播性檢查的責任是確認產物身分與建置條件足夠明確。嚴格 reproducible build 很難在所有專案做到，但 CI/CD 至少要達到「同一次 workflow 的產物可以被查詢、保存、驗證與重新部署」。

這張表讓團隊知道自己目前在哪個成熟度。初期可以先做到 source、dependency、identity；高治理場景再補 SBOM、signature 與 provenance。

常見反模式

反模式的共同問題是讓「綠燈」失去指向性。當綠燈不知道對應哪份產物，CI/CD 只剩下命令執行紀錄。

下一步路由

• Artifact 術語：讀 Artifact。
• Artifact handoff：讀 Artifact Handoff。
• Gate 邊界：讀 CI gate 與 workflow 邊界。

概念定位

Flaky test 是非決定性的 gate 訊號。它的危害不只在延遲 merge，而是在心理上訓練團隊忽略紅燈；當真回歸出現時，大家也可能先按 rerun。治理目標是把 flaky 分類、隔離、修復，並保持 required checks 的語意可信。

Detect 階段負責證明 flakiness。單次失敗不應直接貼 flaky 標籤；要看同一 commit、同一測試、相近環境下是否出現 pass / fail 不一致，並保存 log、trace、screenshot 或 seed。

Classify 階段負責找根因方向。常見來源包含時間競態、測試順序依賴、共享狀態、外部服務、隨機資料、資源不足、瀏覽器 layout timing、網路模擬與 CI runner 差異；不同來源需要不同修法。

Contain 階段負責保護主線。高價值但暫時 flaky 的測試可以進 quarantine workflow，但必須有 owner、issue、到期日與 replacement gate；直接從 required checks 移除而不追蹤，等於降低品質基線。

Fix 階段負責消除非決定性。常見修法是移除固定 sleep、改用可觀察條件等待、隔離資料、固定 random seed、避免測試共享全域狀態、mock 不穩定外部依賴或調整資源限制。

Re-admit 階段負責把測試放回 gate。測試修完後應在多次 workflow、不同 runner 或足夠時間窗口中穩定通過，再恢復 required checks；否則 gate 會反覆被污染。

分類矩陣

分類矩陣的責任是讓 flaky issue 有明確修復路由。沒有分類時，團隊容易只留下「偶發失敗」這種不可執行標籤。

這張表的邊界是：flaky 可能來自測試，也可能來自產品 race condition。若測試揭露的是產品 race condition，它應該被當成真 bug 處理。

Quarantine 契約

Quarantine 的責任是暫時隔離污染，並維持 gate 的長期品質基線。隔離測試時，要把責任、期限與替代風險控制寫清楚。

1. 每個 quarantine test 必須有 issue 與 owner。
2. 每個 issue 必須標明分類、失敗證據與修復方向。
3. Required checks 若移除測試，要補 replacement gate 或風險說明。
4. Quarantine workflow 仍需定期跑，並回報趨勢。
5. 到期未修復時要重新評估：修、刪、改寫或降級測試責任。

這個契約讓 quarantine 成為治理工具。沒有期限與 owner 的 quarantine 會變成測試墓地，讓主線 gate 永久失去一部分覆蓋。

Tripwire

Tripwire 的責任是提示 flaky 已經從局部問題變成流程問題。

• 團隊看到紅燈第一反應是 rerun：暫停重跑習慣，要求先分類失敗。
• 同一測試一週內多次 quarantine：提升到測試架構或產品 race 檢討。
• Required checks 常因環境問題失敗：檢查 runner、resource、cache 與外部依賴。
• Flaky issue 沒 owner 或沒期限：把 quarantine 視為未完成修復，不視為已處理。

下一步路由

• Flaky 術語：讀 Flaky Test。
• Failure routing：讀 CI 失敗到修復發布流程。
• Gate 邊界：讀 CI gate 與 workflow 邊界。

CI/CD 的責任是提供一致的判讀入口。當 workflow 顯示失敗時，團隊需要能快速判斷是 lint、test、build、package、Artifact Handoff、deploy 還是 Rollback Strategy 階段出問題，並知道下一步該回到本機重現、修正、重新提交，還是暫停發布。

前置知識卡片

用原子化卡片整理 Artifact、Required Checks、Artifact Handoff、Environment Protection、Preview Environment、Rollout Strategy、Rollback Strategy、Migration、Backfill、Image Digest、Release Channel、Infrastructure Drift、Function Alias 與 Flaky Test 等核心術語。流程文章專注情境判讀與決策順序，術語背景交由卡片維持一致。

學習路線

學習路線先從失敗處理與 gate 邊界開始，因為 CI/CD 的價值會在紅燈時最清楚。當讀者能判讀失敗位置與下一步路由，再依部署場域進入前端、後端、App、Docker 或本 blog 專案案例。

與其他教學的分工

CI/CD 教學負責日常工作流程與部署場域差異，Backend 可靠性模組負責系統層可靠性判斷。讀者想知道 workflow 失敗後怎麼修、發布 gate 怎麼切、前端與後端部署流程差在哪裡，讀本系列；想知道 CI 在 release gate、SLO、load test 與可靠性治理中的位置，回到 模組六：可靠性驗證流程。

Go、Python 或其他語言教材只需要保留測試寫法與本機命令。當內容開始涉及 workflow event、required checks、preview deployment、container registry、mobile signing、artifact、cache 或 branch protection，就應該移到本系列，讓不同語言共用同一套 CI/CD 操作語意。

判讀訊號

• GitHub Actions 紅燈後，不知道該看哪個 job。
• 本機測試通過，但 CI 失敗。
• 測試失敗後仍有部署 workflow 啟動。
• deploy 失敗時，團隊分不清 build artifact、部署權限與測試 gate 的責任。
• 前端、後端、App 與 Docker 使用同一套發布說明，導致場域細節混在一起。
• workflow 只有命令清單，沒有說明失敗後的處理路由與部署場域邊界。

下一步路由

• 想處理 GitHub Actions 紅燈：讀 CI 失敗到修復發布流程。
• 想理解 CI gate 原理：讀 CI gate 與 workflow 邊界。
• 想理解前端部署：讀 前端部署 CI/CD。
• 想理解後端部署：讀 後端部署 CI/CD。
• 想理解 App 發布：讀 App 部署 CI/CD。
• 想理解 Docker / image 流程：讀 Docker / Image 部署 CI/CD。
• 想理解 Serverless 發布：讀 Serverless 部署 CI/CD。
• 想理解資料處理任務發布：讀 Data Pipeline 部署 CI/CD。
• 想理解 IaC / 平台變更發布：讀 IaC / Platform 部署 CI/CD。
• 想理解 Flutter/Electron/Tauri 類客戶端發布：讀 Desktop Client 部署 CI/CD。
• 想理解 SDK / NPM / PyPI 發版：讀 Package / Library Release CI/CD。
• 想維護本 blog 的 workflow：讀 本 blog 專案部署。
• 想讓測試與發布共用同一份產物：讀 Artifact 與可重播性。
• 想治理不穩定測試：讀 Flaky test 治理。
• 想理解可靠性層的 CI 分層：讀 6.1 CI pipeline。
• 想理解發布 gate：讀 6.8 Release Gate 與變更節奏。
• 想理解 infra 變更的 plan / apply 流程怎麼走 CI：讀 Infra 走 PR 流程與自動化護欄。

本卡抽自 blog CI 的 Playwright install step 反覆 timeout 事件。Playwright 1.59 在 Node.js 24.16.0 上 extract-zip silent hang，表面看是「下載太慢 / timeout 太緊」，實際是 upstream regression。limitation：evidence 來自單一 CI 事件，但 silent hang 模式在 Docker build、cron job、database migration 等場景都出現過。

完整 case study 見 CI step silent hang。

核心原則

非互動 process 的 log 輸出中，最後一行成功訊息（happy log）到被外部 cancel 之間的大段時間無輸出（時間真空），是 silent hang 的判讀訊號。

技術人員習慣在 log 裡搜尋 error keyword 找失敗原因。但 silent hang 沒有 error keyword — process 沒 crash，只是不再做任何事。辨識 silent hang 需要轉換訊號類型：從「訊息內容」轉到「訊息時序」。

情境

CI step 跑了 15 分鐘被 timeout cancel。最後一行 log 是「chromium 下載 100% 完成」— 這是 happy log，直覺判斷是「下載慢、timeout 太緊」。加了 cache + bump timeout 到 25 分鐘，仍然頂到上限被 cancel。

回頭看 detailed log 的 timestamp：

12026-05-27T09:59:44.110Z  | 100% of 170.4 MiB
22026-05-27T10:24:15.201Z  ##[error]The operation was canceled.

24 分 31 秒的時間真空。下載 2 秒完成，之後 process 完全沒有任何 log 輸出直到被 cancel。

理想做法

CI step timeout 時，先抓四個 timestamp 判斷是否 silent hang，再決定修法：

1. Step 開始的 timestamp
2. Step 結束（cancel / fail）的 timestamp
3. 最後一行有意義輸出的 timestamp
4. 計算 #3 到 #2 之間的時間真空

真空相對該 step 正常輸出節奏明顯異常（CI extract 類場景通常秒級輸出、真空超過數分鐘即可疑）且最後一行是 happy log → silent hang 嫌疑高 → 用症狀詞查 upstream issue tracker，不是加 timeout。

三類 timeout 模式的修法不同：

沒這樣做的麻煩

• 反覆加 timeout：每次都「差一點」（頂到上限），每次都以為「timeout 不夠」，實際上 process 永遠不會自己結束
• Cache 是假瓶頸：直覺判斷「下載慢 → 加 cache」，但瓶頸在 extract hang（下載只花 2 秒）
• False positive 越雕越精緻：cache key 調整、timeout 微調、retry 策略 — 每一步單看合理，合起來是把錯誤假設越做越細

判讀徵兆

兩個訊號同時出現時，應該先排除 silent hang 再提其他解法：

1. 非互動 process 跑的時間接近或等於 timeout 上限（「頂到上限」模式）
2. 最後一行 log 是成功訊息（下載完成 / build succeeded / tests passed）

另一個後設訊號：同方向修法（加 timeout / 加 cache / 加 retry）2 次都仍頂到上限 — 這時候問題幾乎確定不是「時間不夠」。對應 #20 同方向反覆失敗的轉折點。

跟其他抽象層原則的關係

• → #20 同方向反覆失敗的轉折點：本案例是 #20 在 CI timeout 場景的 evidence — 第二次 bump timeout 仍 fail 時就該停下來換思路
• → #199 一篇文章只承擔一種功能：本卡的來源文章原本放在 posts/，實際是 debugging case study，搬到 work-log/ 後從中抽出本卡，是 #199 拆分動作的實例

核心議題：CI step 看起來「跑了很久才 timeout」時，要分辨「真的時間不夠」跟「silent hang 占滿時間」 — 兩者修法完全不同。Silent hang 的訊號是「最後一行 happy log 到 cancel 之間有大段時間真空」、不是「最後一行錯誤訊息」。第一次歸因錯誤後、第二次 fail 不該再加 timeout、該停下來重看 detailed log。 案例骨幹：本 blog 的 Playwright CI 一直 timeout、初診「cache 缺失 + timeout 太緊」加了 cache + bump timeout、仍 timeout。重看 detailed log 發現 chromium 下載 2 秒完成、之後 24 分 31 秒完全沒任何 log 才被 cancel — Playwright 1.59 在 Node.js 24.16.0 的 extract-zip regression（microsoft/playwright#41000、上游 nodejs/node#63487）。升 Playwright 1.60.0 後該 step 從 25 分鐘卡死降到 22 秒。

1. Silent hang 是 happy log 的 anti-signal

CI step timeout 時、第一個本能是看「step 跑了多久」。15 分鐘 timeout 然後被砍、直覺判斷是「時間不夠、bump timeout」。這個直覺對應的失敗模式是「step 真的需要 16 分鐘才能跑完」。

但有另一種失敗模式長得很像、修法完全不同：silent hang — step 在某個點之後就不再輸出任何 log、process 仍在執行（沒有 crash）、直到外部 timeout 才被砍。表面看跟「時間不夠」一樣（step 跑很久才被 cancel）、但根因是 process 本身卡死、給多少時間都跑不完。

辨識 silent hang 的關鍵訊號是「最後一行 happy log 到 cancel 訊息之間有大段時間真空」。「Happy log」指的是看起來成功的訊息（例：下載 100% 完成、build succeeded、X tests passed）— 這類訊息特別會誤導判斷、因為它讓人以為任務在進展。Silent hang 開始之前的最後一行通常正是這種 happy log、是正常結束訊號的反面。

三類 timeout 模式的對照

第三種最容易誤判、因為「log 之間沒輸出」沒被當成訊號 — 但訊息真空本身就是訊號。寫 debug log 的人會記得補 error 訊息、但 silent hang 通常發生在工具內部的某個沒輸出 log 的等待點、所以沒有 error 訊息可看。

2. 為什麼「cache 缺失 + bump timeout」的初診是 false positive

第一次看 CI fail log 時、有三件容易抓到的事：

1. workflow YAML 裡的 timeout-minutes: 15
2. step 跑了 15m 6s（幾乎等於 timeout 上限）
3. step 名稱是 Install Playwright browsers（要下載 170 MiB）

直覺合成的結論：「cache 缺失 + timeout 太緊」。這結論看起來「應該對」 — 因為這兩個都是「Install Playwright browsers」眾所周知的優化點。修法：加 actions/cache + bump timeout 25 min。

修完仍 timeout、但這次跑 25m 6s（一樣頂到上限）。

這時的訊號應該是「同樣的 step 在 1.67 倍的 timeout 下仍頂到上限」 — 如果是時間不夠、bump 之後該往中間靠（譬如完成在 18-20 min）；如果一直頂到上限、意思是 step 不會自己結束、是 hang。

但初診時很容易略過這個訊號、轉而繼續想「是不是 cache step 設定有問題？」。這個歸因方向是錯的、因為前置假設「cache 是瓶頸」本身就沒驗證過。

一輪 false positive 的 anatomy

每一步單看都合理、合起來就是把 false positive 越雕越精緻。這個 anatomy 對任何「初診沒驗證就改」的場景都適用、不限 CI。

3. WRAP 的 R 在第二次 fail 時是 stop 訊號

WRAP 決策框架的 R（Reality Test）原則是「需要什麼事證才能證明這個方法可行？」。它不只是決策前的檢查、更是連續失敗後的 stop 訊號。

第二次 fail 時、繼續同方向加 timeout 是自動駕駛模式。WRAP 在這個位置該提醒的事：

• 「兩次同類修法都沒解、是不是前置假設錯了？」
• 「我有沒有資料去判斷真正卡哪？」（資料充足度閘門）
• 「同類問題的 base rate 是什麼？」（基本率思考）

Stop 訊號的觸發條件是「同方向修法連續 fail 2 次」、不是「fail 3 次」。第二次就該回到資料層；第三次已經是浪費 cycle 而且強化錯誤假設。

實際上第二次 fail 後做的對的事是停下來、grep detailed log 的 timestamp 序列、發現「下載完成」跟「cancel」之間有 24 分鐘空白 — 這時才確認是 silent hang。如果第二次沒做這個轉折、第三次大概率是「換更大的 timeout」或「換不同的 cache key」、仍 fail。

4. Detailed log 的關鍵讀法：找「沒輸出的時間段」

CI 平台的 step log 通常很長、人眼掃容易跳過。看 silent hang 嫌疑時、讀法不是順序讀、是抓四個 timestamp：

1. Step 開始的 timestamp（log header 通常有）
2. Step 結束（cancel / fail）的 timestamp
3. 最後一行有意義輸出的 timestamp
4. 計算 #3 到 #2 之間的時間真空

真空夠大（> 1 分鐘）+ #3 是 happy log = silent hang 嫌疑高。

GitHub Actions 用 gh CLI 的具體做法：

1# 取某個 step 的所有 log（filter step 名稱）
2gh run view <run-id> --log --job <job-id> | rg "Install Playwright browsers"
3
4# 抓最後幾行看真空尾巴
5gh run view <run-id> --log --job <job-id> | rg "Install Playwright browsers" | tail -3

本案例的最後 3 行（簡化過）：

12026-05-27T09:59:44.110Z  | 100% of 170.4 MiB
22026-05-27T10:24:15.201Z  ##[error]The operation was canceled.

24 分 31 秒真空、最後一行 happy log 是「下載 100% 完成」 — silent hang 確認。

這個讀法的核心是「時間真空優先於訊息內容」。技術人員習慣讀訊息內容找 error keyword、但 silent hang 沒有 error keyword 可找、只有時間真空。轉個訊號類型才看得到。

5. Upstream issue 搜尋的優先序

Silent hang 確認後、下一步通常不是繼續 reason 根因、是去查 upstream issue tracker。Silent hang 多半是工具 / 依賴的 bug、而非自己 config 錯 — 因為 config 錯通常有 error message、不會 silent。

查詢策略：

1gh api 'search/issues?q=repo:<upstream>/<repo>+<symptom keywords>+is:issue&per_page=10&sort=updated'

關鍵是 keyword 選擇用「症狀詞」而不是「猜測詞」。症狀詞描述讀者實際觀察到的現象（hangs after download、stuck during extract），猜測詞描述讀者推測的根因（slow、timeout、network issue）。猜測詞會找到大量無關 issue；症狀詞通常直接命中。

本案例查詢 playwright install hangs chromium 第二筆結果就是 issue #41000、標題完全匹配「playwright install chromium hangs after download completes on Node.js 24.16.0 (extract-zip)」。Issue 詳情指向上游 nodejs/node#63487、給出兩個 workaround（升 Playwright 1.60.0 或 pin Node 24.15.0）。從查詢到確認根因、全程不到 5 分鐘。

為什麼 issue tracker 該優先於 self-reasoning

技術人員的 instinct 是「自己想出根因」。但 CI silent hang 這類問題、根因通常在工具版本、runtime 版本、OS、container image 的微妙交互、不在自己的 codebase。Reasoning 找不到的東西、社群 issue tracker 經常已經有人回報過。

「先 reason 再查」跟「先查再 reason」的取捨：

Silent hang 預設屬於第二類、應該優先查 issue tracker。

6. 整合：訊號 → 行動 mapping

把本案例的經驗整理成可重用的訊號表：

這張表的順序很重要：每一步的「該做的事」是下一步的「前置條件」。略過任一步、後面的判斷會建立在錯誤假設上。

適用範圍

「Silent log 是 happy log 的 anti-signal」這個原則對所有非互動 process（CI、cron job、background worker、container init）都適用：

• Docker build 卡住（特別是 RUN apt-get / npm install / pip install）— 同類 silent hang 模式
• CI cache restore 卡住 — 大量小檔案的 cache 操作可能 silent hang
• Database migration 卡住 — schema 變更 + 長 transaction 可能 silent hang
• 任何 process 跑時間接近 timeout 上限被 cancel — 先檢查是否 silent hang 才提解法

「WRAP R 在第二次 fail 時是 stop 訊號」這條原則不限 CI、適用所有「同方向修法重複 fail」的場景：debug、設定調校、效能優化。

參考資料

• microsoft/playwright issue #41000 — 本案例的 upstream issue（Playwright 1.57-1.59 在 Node 24.16.0 extract-zip hang）
• nodejs/node issue #63487 — Node 24.16 extract-zip / yauzl regression 上游
• 同 blog 文章：WRAP 決策框架的 R 階段操作 — Reality Test 詳細用法

核心術語

卡片與流程文章分工清楚。卡片負責名詞與邊界，流程文章負責情境判讀與操作路由。

Claude Code GitHub Actions 讓 Claude 直接參與你的 GitHub 工作流程，主要功能：

• 互動式助手 — 在 PR/Issue 留言 @claude，Claude 會分析程式碼並回覆
• 自動 Code Review — PR 開啟時自動審查變更
• CI 除錯修復 — build 失敗時自動分析錯誤並修復

完整功能說明參考 官方文件。

設定方式

/install-github-app（推薦）

在 Claude Code 終端執行 /install-github-app，它會引導你完成所有設定。

流程中的關鍵步驟：

1. 選擇 repo — 指定要安裝的 GitHub repository
2. 安裝 Claude GitHub App — 自動安裝到指定 repo，授予 Contents、Issues、Pull requests 的 Read & Write 權限
3. 選擇認證方式 — 選擇 long-life token 會產生 OAuth token，自動寫入 GitHub Secrets 為 CLAUDE_CODE_OAUTH_TOKEN
4. 建立 workflow 檔案 — 自動建立並 push 兩個 workflow：
   • claude.yml — @claude 互動回覆
   • claude-code-review.yml — PR 自動 code review

完成後不需要額外設定。

手動設定（使用 Anthropic API Key）

如果不想用 /install-github-app，可以手動操作：

1. 前往 github.com/apps/claude 安裝 App 到你的 repo
2. 到 repo 的 Settings → Secrets and variables → Actions，新增 ANTHROPIC_API_KEY
3. 手動建立 workflow 檔案到 .github/workflows/

兩種認證方式的差異：

加入 CI 自動除錯

/install-github-app 建立的 workflow 只處理 @claude 互動和 code review。如果你想在 build 失敗時自動觸發 Claude 修復，需要修改既有的 deploy workflow。

首先，補上 Claude 需要的權限（原本可能只有 contents: read）：

1permissions:
2  contents: write        # Claude 需要寫入修復後的檔案
3  pull-requests: write   # Claude 可能需要建立 PR
4  issues: write          # Claude 回報結果
5  pages: write           # 原本的 deploy 權限
6  id-token: write        # 原本的 deploy 權限

然後在 build 步驟加入 Claude 除錯邏輯：

 1# 在原本的 build step 加上 continue-on-error 和 id
 2- name: Build
 3  id: hugo-build
 4  run: hugo --minify 2>&1 | tee hugo-build-output.txt
 5  continue-on-error: true
 6
 7# Build 失敗時觸發 Claude 除錯
 8- name: Claude Debug on Build Failure
 9  if: steps.hugo-build.outcome == 'failure'
10  uses: anthropics/claude-code-action@v1
11  with:
12    # 依你的認證方式擇一
13    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
14    # anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
15    prompt: |
16      Hugo build failed. Here is the error output:
17
18      $(cat hugo-build-output.txt)
19
20      Please analyze the error, find the problematic file(s),
21      fix the YAML front matter or content issue, and commit the fix.
22    claude_args: "--max-turns 10"
23
24# 修復後重新 build 驗證
25- name: Retry build after fix
26  if: steps.hugo-build.outcome == 'failure'
27  run: hugo --minify

核心設計：

1. continue-on-error: true — build 失敗不中斷流程，讓後續 Claude 步驟有機會執行
2. if: steps.hugo-build.outcome == 'failure' — 只在失敗時觸發，正常 build 不消耗 API 額度
3. 修復後重新 hugo --minify 驗證是否成功

計費方式

計費取決於你使用哪種認證方式：

OAuth token 的額度是共用的，GitHub Actions 跑多了會擠壓你日常在 claude.ai 和 CLI 的使用額度。如果 CI 觸發頻繁，建議改用 API Key 避免互相影響。

詳細的費率可參考 Claude 定價頁面。

降低成本的設定

搭配 CLAUDE.md

在 repo 根目錄建立 CLAUDE.md，Claude 會自動讀取作為上下文，提升修復準確度。

參考資料

• Claude Code GitHub Actions 官方文件
• claude-code-action GitHub Repo
• Setup Guide