awoooi/docs/adr/ADR-057-adopt-gitea-pr-api.md

ADR-057: Drift Adopt 端點 — Gitea PR API 實作路徑

狀態: ✅ 已批准並實作 日期: 2026-04-04 決策者: 統帥 + 首席架構師 關聯 ADR: ADR-056 (Config Drift Detection) 觸發原因: 首席架構師 C2 裁示 — API Pod 內執行 git add -A 有安全漏洞

---

背景

問題陳述

ADR-056 中 adopt() 端點的設計目標：將 K8s 實際狀態的合法漂移反向寫回 Git（使 Git 承認此次變更）。

原始實作使用 _git_push() 在 API Pod 內執行 git add -A && git commit && git push gitea main，存在：

1. 安全風險: git add -A 可能誤提交 Secret/ConfigMap 等敏感資料
2. 多副本問題: 多個 API Pod 同時執行 git 操作會造成 conflict
3. 認證問題: API Pod 需要持有 Gitea 認證，擴大攻擊面
4. Bypass 審核: 直接 push main 繞過 PR review 流程

---

決策（草案）

D1: adopt() 端點改用 Gitea PR API

流程：

用戶按下 adopt → API 呼叫 Gitea API 建立 PR → SRE review → merge

具體實作：

1. API 呼叫 POST /api/v1/repos/{owner}/{repo}/pulls（Gitea API）
2. PR title: chore: adopt drift — {namespace} {summary}
3. PR body: 包含漂移詳情、Nemotron 意圖分析、影響評估
4. PR 建立後推送 Telegram 通知 SRE review

D2: 分支命名規範

drift/adopt-{report_id[:8]}-{timestamp}

API 建立 branch 並 commit 對應 YAML 變更，再開 PR。

D3: API Pod 認證方式

使用 Gitea API Token（現有 GITEA_API_TOKEN secret），只需 PR 建立權限，不需要 push main 權限。

---

實作前置條件

• 統帥批准此 ADR (2026-04-05)
• 確認 GITEA_API_TOKEN 已在 K8s Secret 中（kubectl patch 注入）
• 確認 Gitea API /repos/wooo/awoooi/pulls 端點可用（測試通過）
• Phase 2: YAML diff 精確生成邏輯（目前加注解，欄位值需人工更新）

---

替代方案

方案	理由未採用
繼續 git push main（原實作）	安全風險 + 多副本問題
完全移除 adopt()	失去 GitOps 閉環能力
透過 Webhook 觸發 Gitea CI	複雜度高，與現有 CD 流程耦合

---

狀態追蹤

項目	狀態
首席架構師 C2 裁示（暫停 git push）	✅ 2026-04-04
adopt() 端點回傳 501	✅ 2026-04-04
ADR-057 起草	✅ 2026-04-05
統帥批准 ADR-057	✅ 2026-04-05
Gitea PR API 實作	✅ 2026-04-05 — commit a81bf50
GITEA_API_TOKEN 注入 K8s Secret	✅ 2026-04-05