# 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 權限。

---

## 實作前置條件

- [x] 統帥批准此 ADR (2026-04-05)
- [x] 確認 `GITEA_API_TOKEN` 已在 K8s Secret 中（kubectl patch 注入）
- [x] 確認 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 |