Knowledge Cards on Tarragon

CI Pipeline

Wed, 06 May 2026 00:00:00 +0000

CI Pipeline 的核心概念是「在合併前自動驗證變更」。它把品質門檻前移，讓問題在進主線前被發現。

概念位置

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 要定義必跑檢查、失敗回饋路由與執行時間上限，讓綠燈具備可發布前提。

CD Pipeline

Wed, 06 May 2026 00:00:00 +0000

CD Pipeline 的核心概念是「把已驗證產物安全交付到目標環境」。它把 build、artifact、deploy 與 release gate 串成可重播流程。

概念位置

CD Pipeline 位在 CI 驗證之後，負責 artifact promotion、部署執行、環境保護與回復路徑。

可觀察訊號

同一份 artifact 需要在多個環境推進。
發布步驟需要審核、權限或時間窗控制。
發布失敗時需要可回退或可修復路徑。

接近真實服務的例子

靜態站會在 CI 成功後上傳 artifact 到 hosting。後端服務會推進同一個 image tag 到 staging 與 production，並以 rollout strategy 控制風險。

設計責任

CD Pipeline 要明確定義放行條件、部署順序、例外流程與回復策略，確保發布節奏與風險控制一致。

Required Checks

Wed, 06 May 2026 00:00:00 +0000

Required Checks 的核心概念是「把合併條件綁定到檢查結果」。它讓主線保護不依賴人工記憶，而依賴可觀測狀態。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Artifact

Wed, 06 May 2026 00:00:00 +0000

Artifact 的核心概念是「可被追溯的交付產物」。它是 build 的輸出單位，也是 test 與 deploy 的共同依據。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Artifact Handoff

Wed, 06 May 2026 00:00:00 +0000

Artifact Handoff 的核心概念是「測試與發布共用同一份產物」。它把可重現性從口頭約定變成流程保證。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Environment Protection

Wed, 06 May 2026 00:00:00 +0000

Environment Protection 的核心概念是「用環境層 gate 控制正式發布」。它把環境風險從 workflow 腳本外顯成可檢查規則。

概念位置

Environment Protection 位在部署 job 與目標環境之間，包含 reviewer、wait timer、branch policy 與 secret scope。

可觀察訊號

測試綠燈後仍需要人工批准才能進 production。
不同環境需要不同發布權限與審核規則。
發布失誤常來自權限配置或保護規則缺失。

接近真實服務的例子

GitHub Actions deploy job 指向 production environment，需指定 reviewer 批准後才可部署。staging 則採自動放行。

設計責任

Environment Protection 要定義環境分層、審核責任、發布時窗與例外流程，讓高風險發布有明確控制面。

Preview Environment

Wed, 06 May 2026 00:00:00 +0000

Preview Environment 的核心概念是「在合併前提供接近正式環境的可驗證入口」。它把 code review 從靜態 diff 延伸到真實互動行為。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Rollout Strategy

Wed, 06 May 2026 00:00:00 +0000

Rollout Strategy 的核心概念是「用分批推進控制發布風險」。它讓變更從小範圍驗證逐步擴大到全量。

概念位置

Rollout Strategy 位在部署執行與正式流量切換之間，常見型態包含 rolling、canary、blue-green 與 phased rollout。

可觀察訊號

發布後需要觀察一段時間再擴大流量。
高風險變更不適合一次全量切換。
團隊需要把監控訊號綁定到擴大量決策。

接近真實服務的例子

後端 API 先以 10% canary 流量觀察錯誤率與延遲，再逐步推進。App 發布以 phased rollout 控制商店推送比例。

設計責任

Rollout Strategy 要定義推進節點、觀察指標、阻擋條件與升降級節奏，讓部署風險可被量化管理。

Rollback Strategy

Wed, 06 May 2026 00:00:00 +0000

Rollback Strategy 的核心概念是「在異常發布後縮小影響範圍並回到可用狀態」。它屬於部署設計的一部分，需要在事故前完成。

概念位置

Rollback Strategy 位在 deploy、rollout 與 incident handling 之間，通常要和資料遷移、feature flag 與流量切換一起設計。

可觀察訊號

發布後錯誤率或延遲快速升高。
新舊版本存在相容性風險。
團隊需要在分鐘級別恢復核心功能。

接近真實服務的例子

靜態站可回退前一版 artifact。後端服務可回退 image tag 並暫停新 migration。App 場域可先用 remote config 關閉新功能，再走 hotfix 發版。

設計責任

Rollback Strategy 要定義觸發條件、責任人、回退動作與回復後驗證，並定期演練。

Deployment Dry Run

Wed, 06 May 2026 00:00:00 +0000

Deployment Dry Run 的核心概念是「在正式部署前預演關鍵步驟」。它讓流程在低風險條件下先驗證 artifact、權限與目標環境配置。

概念位置

Deployment Dry Run 位在 build / test 完成後、production deploy 之前，通常以 preflight check、模擬發布或目標環境校驗實作。

可觀察訊號

正式部署常失敗於權限、路徑或配置差異。
團隊需要在不影響使用者前提下驗證部署條件。
發布流程包含高成本動作或不可逆步驟。

接近真實服務的例子

部署腳本先驗證 artifact 存在、環境密鑰可讀、目標 bucket 或 registry 可寫，再進入正式 deploy。

設計責任

Deployment Dry Run 要定義檢查範圍、成功條件、失敗回饋與執行時機，並和正式部署命令保持一致語意。

Migration

Wed, 06 May 2026 00:00:00 +0000

Migration 的核心概念是「把舊狀態受控推進到新狀態」。它不只涉及資料庫 schema，也包含資料回填、相容窗口與發布順序。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Branch Protection

Wed, 06 May 2026 00:00:00 +0000

Branch Protection 的核心概念是「把主線寫入條件制度化」。它把 required checks、review policy 與合併限制集中成 repository gate。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Readiness / Health Check

Wed, 06 May 2026 00:00:00 +0000

Readiness / Health Check 的核心概念是「服務活著」與「服務可接流量」是兩個不同訊號。部署放行通常依賴 readiness，而非僅看 process alive。

概念位置

Readiness / Health Check 位在 rollout、load balancer 與 runtime platform 之間，是流量切換前的核心 gate。

可觀察訊號

部署後健康檢查綠燈但請求仍大量失敗。
新版啟動中就提早接到流量。
rollout 失敗時缺少可觀測放行條件。

接近真實服務的例子

Kubernetes liveness 通過只代表 process 存活；readiness 通過才代表連線池、依賴服務與必要資料都已準備完成。

設計責任

Readiness / Health Check 要定義檢查內容、容錯窗口與失敗處理，讓 rollout decision 有可信訊號。

Container Registry

Wed, 06 May 2026 00:00:00 +0000

Container Registry 的核心概念是「管理可部署 image 的供應鏈節點」。它負責保存、授權、保留與推進已驗證影像。

概念位置

Container Registry 位在 image build、scan、promotion 與 runtime deploy 之間，連接 CI 產物與環境發布。

可觀察訊號

同一 tag 在不同環境對應內容不一致。
部署因拉取權限或鏡像不存在失敗。
線上 image 缺少來源與掃描紀錄的反查路徑。

接近真實服務的例子

團隊以 immutable digest 推進 staging 與 production，並透過 registry policy 控制 retention、pull 權限與 promotion 路徑。

設計責任

Container Registry 要定義命名策略、權限模型、保留策略與來源追溯，讓 image 發布具備可審計性。

App Signing

Wed, 06 May 2026 00:00:00 +0000

App Signing 的核心概念是「簽章憑證即發布能力」。它決定 artifact 是否被平台接受與使用者裝置信任。

概念位置

App Signing 位在 app build 與 release channel 之間，涉及 certificate、provisioning profile、keystore 與 secret 管理。

可觀察訊號

發布因簽章失敗中斷。
憑證過期導致發版中斷。
金鑰輪替缺乏演練造成交付風險。

接近真實服務的例子

iOS 發版需匹配正確 certificate 與 provisioning profile，Android 發版需維護 keystore 一致性與安全儲存。

設計責任

App Signing 要定義密鑰保存、輪替節奏、權限分離與緊急回復流程，確保發布能力可持續。

Flaky Test

Wed, 06 May 2026 00:00:00 +0000

Flaky Test 的核心概念是「同一版本在相同條件下測試結果不穩定」。它會把紅燈從有效訊號降級成噪音，直接影響 CI gate 信任度。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Backfill

Thu, 21 May 2026 00:00:00 +0000

Backfill 的核心概念是「用新邏輯受控補算既有資料」。它通常和 Migration 共享相容窗口，並依賴 Checkpoint 保存進度。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Checkpoint

Thu, 21 May 2026 00:00:00 +0000

Checkpoint 的核心概念是「保存可接續的處理進度」。它讓 Backfill 與 Rerun 可以從明確位置恢復，避免每次都從頭開始。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Rerun

Thu, 21 May 2026 00:00:00 +0000

Rerun 的核心概念是「用明確條件重新執行同一段流程」。它和 Flaky Test 的治理有關，也常依賴 Checkpoint 判斷接續位置。

概念位置

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

可觀察訊號

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

接近真實服務的例子

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

設計責任

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

Image Digest

Thu, 21 May 2026 00:00:00 +0000

Image Digest 的核心概念是「用內容雜湊識別不可變 image」。它補足 Container Registry 的命名治理，讓 Artifact Handoff 可以鎖定精準產物。

概念位置

Image Digest 位在 image build、scan、registry promotion 與 runtime deploy 之間，通常以 sha256:... 形式標識 image manifest 或 image index。

可觀察訊號

latest 或 mutable tag 造成 staging 與 production 內容分叉。
production runtime 需要反查實際跑的 image。
掃描結果需要和部署內容精準對齊。

接近真實服務的例子

CI build image 後推到 registry，scan 報告綁定 digest。Kubernetes manifest 在 production 使用同一個 digest，事故時可從 running pod 反查 workflow run 與 source commit。

設計責任

Image Digest 要納入 deployment manifest、scan report、release note 與 rollback 記錄，讓 image 發布具備可追溯與可審計能力。

SBOM

Thu, 21 May 2026 00:00:00 +0000

SBOM 的核心概念是「列出 artifact 內含軟體元件」。它把 Artifact 的依賴組成顯性化，並支援 image scan、license review 與 vulnerability exception。

概念位置

SBOM 位在 build、scan、release 與 compliance review 之間，常見格式包含 SPDX、CycloneDX 或工具自訂輸出。

可觀察訊號

團隊需要知道 image 或 package 包含哪些 dependency。
漏洞公告需要快速判斷受影響 artifact。
高治理環境要求 release 產物附帶供應鏈證據。

接近真實服務的例子

Container image 發布時同時產生 SBOM，scan gate 依 SBOM 對照 CVE 與 license policy。若 base image 發現 critical vulnerability，團隊可查哪些 release digest 受影響。

設計責任

SBOM 要定義產出時機、格式、保存位置、artifact 對應關係與例外審核流程，讓供應鏈風險可以被查詢與治理。

Release Channel

Thu, 21 May 2026 00:00:00 +0000

Release Channel 的核心概念是「用通道控制版本接觸範圍」。它是 Rollout Strategy 的分發面，常和 App Signing 與 update feed 一起設計。

概念位置

Release Channel 位在 artifact 發布與使用者取得之間，常見通道包含 internal、alpha、beta、stable、enterprise、nightly 與 rollback channel。

可觀察訊號

同一產品需要內測、公開測試與正式版本分流。
錯誤版本需要停止擴散或切回回復通道。
客戶端更新需要依風險分批推進。

接近真實服務的例子

桌面 app 先把 signed installer 推到 internal channel，驗證更新成功率後再推 beta channel，最後推 stable channel。若 stable 版本出現 crash，feed 可切回 rollback channel 或暫停更新。

設計責任

Release Channel 要定義通道用途、進入條件、artifact 命名、可見範圍、停損條件與回復路徑，讓版本擴散具備控制面。

Update Feed

Thu, 21 May 2026 00:00:00 +0000

Update Feed 的核心概念是「告訴已安裝客戶端該取得哪個版本」。它連接 Release Channel 與 App Signing，讓自動更新具備信任與回復能力。

概念位置

Update Feed 位在 signed artifact、release channel 與已安裝 app 之間，常包含版本號、下載 URL、signature、checksum、release notes 與最低支援版本。

可觀察訊號

客戶端需要自動偵測新版本。
beta 與 stable 使用者需要看到不同版本。
錯誤版本需要從更新來源撤下。

接近真實服務的例子

Electron app 啟動時讀取 stable feed，取得最新 signed installer 與 signature。若新版本 crash rate 升高，團隊先撤下 feed 指向，讓未更新使用者停止取得錯誤版本。

設計責任

Update Feed 要定義簽章驗證、channel 分流、版本比較、fallback installer、撤版策略與 telemetry，讓已安裝客戶端安全升級。

Infrastructure Drift

Thu, 21 May 2026 00:00:00 +0000

Infrastructure Drift 的核心概念是「真實環境狀態與宣告檔分叉」。它會削弱 Environment Protection 與 deployment review 的可信度，並影響下一次 plan / apply 的安全性。

概念位置

Infrastructure Drift 位在 IaC state、cloud resource、手動 hotfix 與外部 controller 之間，常由 console edit、事故修復、provider 預設值或自動調整造成。

可觀察訊號

plan 顯示大量非預期變更。
production 資源和 repository 宣告不一致。
下次 apply 可能覆蓋事故 hotfix。

接近真實服務的例子

事故中工程師在雲端 console 手動放寬 security group。服務恢復後，IaC plan 顯示 security group 與宣告檔不同；團隊需要判斷這個變更是短期 hotfix 還是應回寫成正式規則。

設計責任

Infrastructure Drift 要定義偵測頻率、owner、修復路由、state repair 與回寫規則，讓平台狀態重新回到可審查流程。

State Lock

Thu, 21 May 2026 00:00:00 +0000

State Lock 的核心概念是「讓同一份基礎設施狀態一次只被一個 apply 修改」。它支撐 Infrastructure Drift 的治理，避免 CI job 或人工操作併發覆寫 state。

概念位置

State Lock 位在 IaC state backend、plan / apply workflow 與平台資源之間，常由 Terraform backend、Pulumi state 或平台鎖定機制提供。

可觀察訊號

多個 pipeline 同時 apply 同一個 workspace。
state file 出現併發覆寫或 partial apply 後不一致。
apply 長時間卡住需要判斷 lock 是否仍有效。

接近真實服務的例子

兩個 PR 同時修改 production network。第一個 workflow 取得 state lock 後進入 apply，第二個 workflow 等待或失敗，避免兩次變更同時寫入 state。

設計責任

State Lock 要定義 lock backend、timeout、人工解鎖條件、環境隔離與失敗處理，讓 IaC apply 保持序列化。

Function Alias

Thu, 21 May 2026 00:00:00 +0000

Function Alias 的核心概念是「用穩定名稱指向不可變函式版本」。它讓 Rollout Strategy 可以套用在 serverless function 上，並讓 Rollback Strategy 具備快速切換入口。

概念位置

Function Alias 位在 function version、traffic weight、event source 與 invocation entrypoint 之間，常見於 Lambda alias 或其他 serverless 平台的版本別名。

可觀察訊號

新舊 function version 需要短暫共存。
部分流量需要導向新版本做 canary。
事故時需要把入口切回上一個版本。

接近真實服務的例子

HTTP function 的 prod alias 先把 5% 流量導向 version 42。若錯誤率穩定，逐步提高權重；若錯誤率升高，alias 切回 version 41。

設計責任

Function Alias 要定義版本命名、流量權重、觀測指標、事件來源綁定與回復條件，讓函式發布具備可控入口。

Event Source

Thu, 21 May 2026 00:00:00 +0000

Event Source 的核心概念是「觸發執行的事件入口」。它決定 serverless function 或 worker 何時執行、如何重試、如何進入 dead-letter，並影響 Function Alias 的 rollout 與回復策略。

概念位置

Event Source 位在 queue、topic、HTTP gateway、object storage、scheduler 與 function / worker 之間，負責把外部事件轉成執行請求。

可觀察訊號

函式部署成功，但 invocation 因 trigger 設定失敗。
Queue event 重試造成同一筆資料被重複處理。
事件 schema 漂移導致 subscriber 解析失敗。

接近真實服務的例子

Queue 觸發的 function 以 batch 方式處理訊息。新版本解析失敗時，訊息進入 dead-letter queue；團隊先停用 trigger，再修復 function 或重放事件。

設計責任

Event Source 要定義 trigger 條件、batch size、retry、dead-letter、replay、權限與 schema 契約，讓事件驅動發布具備可觀測回復路徑。