awoooi/docs/operations/CODE-REVIEW-CODEX-GITEA-OPTIMIZATION.md

# Code Review 接 Codex 與 Gitea 推版優化藍圖

| 項目 | 內容 |
|------|------|
| 狀態 | 規劃完成，尚未開始實作 |
| 日期 | 2026-05-06 |
| 範圍 | Code Review、Codex coding 接力、Gitea/GitHub CI/CD 邊界、AI Agent 資安分工 |
| 原則 | 長期以 GitHub 作為雲端主控面，Gitea 保留本地 mirror / fallback，先盤點與同步，再逐步切換 |
| AwoooP 同步 | `docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md` |

## 背景

過去使用 GitHub 作為主要 CI/CD 與 Claude Code 工作入口時，曾發生兩類問題：

1. Code Review 後需要 coding 的工作沒有穩定接力，導致修補、推版、部署流程變得耗時且複雜。
2. Claude Code 或 GitHub Actions 工作流使用 GitHub-hosted runner 時，容易消耗 GitHub 免費額度。

本專案已依 ADR-039 遷移為：

```text
Gitea 作為主倉與 CI/CD 執行面
GitHub 作為只讀備份
```

但從長期可用性角度看，Gitea 部署在本地端，會受到 110 重開機、Docker/Gitea runner、內網服務與儲存狀態影響。若 Git repository、PR、Code Review 與 Codex 接力全部依賴本地 Gitea，開發控制面會跟著本地機房狀態一起中斷。

因此本輪修訂長期方向為：

```text
GitHub 作為雲端主控面：主 repo、PR、Code Review、Codex / Codex Security 接力
本地 runner / deployment plane：build、Harbor push、K8s deploy、內網驗證
Gitea 作為本地 mirror / fallback：保留完整版本與緊急離線備援
```

這不是回到舊的「GitHub-hosted runner 全包 CI/CD」模式，而是把穩定的協作與審查控制面放回 GitHub，同時把高耗時、內網依賴、production deploy 的工作留在 self-hosted runner 與本地部署面。

## 官方事實基線

### GitHub Actions 額度

依 GitHub 官方文件：

- self-hosted runner 使用 GitHub Actions 不消耗 GitHub-hosted runner minutes。
- public repository 使用標準 GitHub-hosted runner 通常免費。
- private repository 使用 GitHub-hosted runner 會消耗帳號方案內的免費 minutes、artifact storage、cache storage，超額後可能被阻擋或計費。
- larger runner 另計，不應視為免費額度。

官方來源：[GitHub Actions billing](https://docs.github.com/en/billing/managing-billing-for-your-products/about-billing-for-github-actions)。

因此統帥的理解是正確的：GitHub 可以正常使用，但要避免把私有 repo 的日常 CI/CD 跑在 GitHub-hosted runner 上。若必須在 GitHub 跑 workflow，優先使用 self-hosted runner 或只保留極短、手動、低頻的檢查。

### Codex 費用與接法

依 OpenAI 官方文件：

- Codex 是可讀取、修改、執行程式碼的 coding agent，可在雲端、CLI、IDE、SDK 等不同介面使用。
- Codex 可用於 code review、bug fix、測試補齊、資安弱點修補等工作。
- Codex app / CLI / cloud 會受到使用者方案、credits、rate limits 與工作環境設定影響。
- 若使用 OpenAI API / Responses API / Codex coding model 自建流程，則走 API token 費用與 API rate limit。

官方來源：[Codex cloud docs](https://platform.openai.com/docs/codex/overview)、[Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan%252525252525252525252525252525252525252525252525252525252528.pdf)、[OpenAI API Pricing](https://openai.com/api/pricing/)。

因此結論是：可以把 Code Review 後的 coding 工作串接到 Codex，但要分成「使用 Codex 產品額度」與「自建 API 工作流費用」兩種路線管理。

## 決策

1. 長期目標改為 GitHub primary：GitHub 作為 AWOOOI 的雲端主 repo、PR、Code Review、Codex / Codex Security 接力入口。
2. Gitea 降級為本地 mirror / fallback / 離線保險，不再長期承擔唯一主控面。
3. Code Review 後的 coding 工作可以串接 Codex，但第一階段採半自動、人工批准，不直接自動合併或部署。
4. Claude Code 不作為推版主控；可保留為開發輔助或審查席位，但不得讓它觸發高頻 GitHub-hosted workflow。
5. Codex 若透過 API 深度整合，需在實作前另外確認費用、token 上限、資料外送與權限邊界。
6. NemoTron 值得作為資安深度分析與工具調用候選升級，但不取代 OpenClaw 主控。
7. 所有目前只存在於 Gitea 的專案、分支、tag、release、workflow 版本與部署相關 commit，都必須完整盤點並轉移或同步到 GitHub；完成前不得切換主控面。

## 目標流程

```text
GitHub push / PR
  -> GitHub Code Review / Codex Security / deterministic review
  -> deterministic review report
  -> coding_task envelope
  -> OpenClaw 分派與風險分級
  -> Codex 產生修補分支或 patch
  -> 測試與 diff 證據
  -> ElephantAlpha / vuln-verifier 複核
  -> 人工批准
  -> GitHub merge
  -> self-hosted runner / 本地 deployment plane
  -> Harbor / K8s / Prometheus 驗證
  -> Gitea mirror 同步
  -> LOGBOOK / AI Governance Event / Memory 摘要
```

第一階段只允許 `suggest-only` 與 `patch-only`，不允許自動 merge、force push、production deploy、secret rotation、RBAC/NetworkPolicy/firewall 修改。

## Code Review 到 Coding Task 的資料契約

建議新增 `coding_task` envelope，承接目前 `.gitea/workflows/code-review.yaml` 與 `scripts/ci_code_review.py` 的 review report。

```json
{
  "schema_version": "coding_task_v1",
  "source": "github_code_review",
  "repo": "awoooi",
  "branch": "main",
  "base_sha": "string",
  "head_sha": "string",
  "risk": "LOW|MEDIUM|HIGH|CRITICAL",
  "summary": "繁體中文摘要",
  "findings": [
    {
      "id": "string",
      "severity": "LOW|MEDIUM|HIGH|CRITICAL",
      "file": "string",
      "reason": "繁體中文原因",
      "recommended_action": "繁體中文建議"
    }
  ],
  "allowed_actions": [
    "create_patch",
    "add_tests",
    "open_draft_pr"
  ],
  "blocked_actions": [
    "auto_merge",
    "production_deploy",
    "force_push",
    "secret_rotation",
    "network_policy_change"
  ],
  "required_reviewers": [
    "critic",
    "vuln-verifier"
  ]
}
```

## Codex 串接策略

### 第一階段：Codex 半自動接力

適用情境：

- Code Review 發現格式、測試、低中風險程式問題。
- 需要補測試、修小 bug、整理型別或錯誤處理。
- 不涉及 production secret、K8s 權限、資料庫破壞性 migration。

建議做法：

1. GitHub / Gitea Code Review 產生 `coding_task_v1`。
2. 由 OpenClaw 或人工把 task 交給 Codex CLI / Codex app。
3. Codex 在隔離 worktree 產生 patch。
4. 本機或 Gitea runner 跑測試。
5. 人工確認後再進 GitHub merge，並由 self-hosted runner / 本地 deployment plane 接續驗證。

優點：最快落地，費用與權限較容易控管。

限制：仍需要人工觸發或人工接力，不是全自動。

### 第二階段：Codex SDK / API 工作流

適用情境：

- 需要把 Code Review finding 自動轉成修補分支。
- 需要整合 AWOOOI approval、AOL、AI governance event、Telegram。
- 需要精準記錄 token、費用、工具呼叫與安全審批。

建議做法：

1. 新增 `code_review_to_coding_task` job。
2. 新增 `codex_patch_runner`，僅允許寫入臨時 worktree。
3. 產生 patch、測試報告與 rollback note。
4. 只建立 draft PR 或 Gitea branch，不自動合併。
5. `HIGH/CRITICAL` 一律需要 `vuln-verifier` 與人工批准。

優點：可追蹤、可治理、可接進 AWOOOI 飛輪。

限制：可能產生額外 API token 費用；需先設 budget、rate limit、資料遮罩與權限範圍。

## GitHub / Gitea 長期優化原則

### GitHub 長期主控用途

- 主 repo 與分支保護。
- PR、Code Review、Codex / Codex Security 接力入口。
- GitHub Issues / Pull Requests 作為可被 Codex cloud 與第三方工具穩定消費的協作面。
- 低頻、短時、非部署型 workflow。
- self-hosted runner 入口，讓 workflow 控制面在 GitHub，但實際執行可回到本地或專用 runner。

### GitHub 避免用途

- 私有 repo 高頻 `ubuntu-latest` workflow。
- push 到 main 後自動跑完整 CI/CD。
- 長時間 LLM / Claude Code / e2e workflow。
- artifact/cache 大量保存。
- 與 Gitea 同時觸發部署，造成雙主控。

### Gitea 長期保留用途

- 本地 mirror，保留 GitHub 不可用時的離線保險。
- 內網備援與災難復原。
- 必要時保留本地只讀查閱與 emergency branch fallback。
- 轉移完成前，暫時保留現有 Gitea CI/CD，避免一次切換造成 release 中斷。

## Gitea 全量轉移到 GitHub 清單

這是長期切換的前置工作，必須納入本次資安網工作項目，並以「完整性」作為驗收標準。

| 範圍 | 轉移要求 | 驗收證據 |
|------|----------|----------|
| Repositories | 所有 Gitea repositories 都要在 GitHub 建立對應 repo 或明確標記封存 | repo 對照表、GitHub URL、owner |
| Branches | 所有仍有用途的 branches 完整同步 | branch count diff、最新 commit SHA 比對 |
| Tags | release tag、deploy tag、rollback tag 完整同步 | tag count diff、tag SHA 比對 |
| Commit history | 不得只複製 main snapshot；需要完整 Git history | `git fsck`、遠端 SHA 比對 |
| Releases / artifacts | 若 Gitea release 有檔案或說明，需要搬遷或標記替代來源 | release inventory |
| Issues / PR | 若仍有未結事項，需要匯出或轉成 GitHub issue | open item mapping |
| Secrets | 不直接搬 secret value；只建立 secret inventory 與 GitHub Actions secret 名稱 | secret 名稱清單、owner、rotation plan |
| Workflows | `.gitea/workflows` 需盤點並決定改寫、停用或保留本地 fallback | workflow migration matrix |
| Webhooks | Gitea webhook 轉 GitHub webhook 或 AwoooP event adapter | webhook endpoint mapping |
| Deploy markers | deploy-marker commits 與 GitOps revision 要能在 GitHub 追溯 | GitHub commit / tag trace |
| Permissions | GitHub teams、branch protection、required checks、CODEOWNERS | permission review 記錄 |

轉移過程中，Gitea 不應被直接刪除或停用；至少保留一段並行 mirror 期，直到 GitHub primary、self-hosted runner、Harbor/K8s deploy、rollback 都被驗證。

此遷移屬於 supply chain security，必須 mirror 到 AwoooP governance。AwoooP 初期只接收 `source_control_migration_event_v1` 作為 evidence，不直接觸發主控切換或部署。

## 建議遷移階段

| 階段 | 目標 | 狀態 |
|------|------|------|
| Phase G0 | 盤點所有 Gitea repos、branches、tags、workflows、webhooks、secrets 名稱 | 未開始 |
| Phase G1 | 建立 GitHub repo / team / branch protection / CODEOWNERS | 未開始 |
| Phase G2 | 全量 mirror Git history、branches、tags，不搬 secret value | 未開始 |
| Phase G3 | 將 Code Review / Codex 接力接到 GitHub PR，但 deploy 仍走本地 runner | 未開始 |
| Phase G4 | self-hosted runner 與本地 deployment plane 驗證 Harbor/K8s/Prometheus 全鏈路 | 未開始 |
| Phase G5 | Gitea 改為 mirror / fallback，主開發入口切到 GitHub | 未開始 |
| Phase G6 | 30 天觀察與 rollback drill 後，再移除多餘 Gitea 主控 workflow | 未開始 |

## AI Agent 分工

| 角色 | 建議定位 |
|------|----------|
| OpenClaw | 主控與分派，負責任務路由、權限邊界、approval gate |
| Codex | coding worker，負責修補、測試、refactor、資安 patch 草稿 |
| Codex Security | 程式碼弱點 identification / validation / remediation 候選 |
| NemoTron | 資安深度分析、工具調用、finding triage、風險摘要 |
| Hermes | 知識沉澱、SOP、LOGBOOK、長期脈絡 |
| ElephantAlpha | 反駁、誤判挑戰、修補風險審查 |
| vuln-verifier | secrets、RBAC、NetworkPolicy、K8s、資安邊界複核 |
| migration-engineer | Gitea、Webhook、CI/CD、GitOps、回滾路徑 |
| critic | 架構審查、規範稽核、回歸風險 |

本專案不建議由單一 Agent 全包。建議採「OpenClaw 主控 + Codex coding + NemoTron 資安分析 + ElephantAlpha 挑戰 + Hermes 記錄」。

## NemoTron 更新評估

2026-05-12 官方來源校準後，NVIDIA Nemotron / NeMo 的方向確實值得列入 AWOOOI 資安網候選：

- NVIDIA 已推出 Nemotron 3 family，主打 Nano / Super / Ultra 尺寸與 agentic AI 應用效率。
- Nemotron 3 Super 是面向 agentic AI 的 MoE / hybrid Mamba-Transformer 模型，官方定位在多步推理與 agent workflow。
- NVIDIA NeMo 產品線已把 agent toolkit、資料治理、模型最佳化與監控納入 enterprise agent 建置方向。

官方來源：[NVIDIA Nemotron 3 family](https://nvidianews.nvidia.com/news/nvidia-debuts-nemotron-3-family-of-open-models)、[Nemotron 3 Super](https://blogs.nvidia.com/blog/nemotron-3-super-agentic-ai/)、[NVIDIA NeMo](https://www.nvidia.com/en-us/ai-data-science/products/nemo/)。

但更新策略應為：

1. 先做官方模型清單與授權確認。
2. 新增候選模型設定，不直接改 production 預設。
3. 對歷史 incident / code review / security finding 做 shadow benchmark。
4. 比較 tool call schema 正確率、誤判率、延遲、費用、繁中品質、secret redaction。
5. 只在 `suggest-only` 風險分析席位 canary。
6. 7-14 天指標穩定後再決定是否升級預設模型。

## 風險與防護

| 風險 | 防護 |
|------|------|
| Codex 自動修出不安全 patch | 第一階段只允許 patch-only，必須人工批准 |
| GitHub 免費額度再次耗盡 | GitHub workflows 避免私有 repo 高頻 GitHub-hosted runner；長任務改 self-hosted |
| Gitea / GitHub 雙主控部署 | 切換前明確指定唯一 deploy controller；GitHub primary 期由 self-hosted runner / 本地 deployment plane 觸發，Gitea 只 mirror |
| Gitea 專案版本漏轉 | 先做 repo/branch/tag/release/workflow/webhook inventory；SHA 比對通過前不切主控 |
| 本地 deployment plane 仍會因重開中斷 | GitHub 只解決控制面可用性；Harbor/K8s/DB/內網 runner 必須另有 cold-start gate |
| LLM 洩漏 secrets | review report 不輸出原始敏感行；送模型前做 redaction |
| Agent 權限過大 | coding task 明列 allowed/blocked actions |
| API 成本失控 | API 化前先設 budget、rate limit、usage metrics、AOL |
| 高風險修補被自動合併 | `HIGH/CRITICAL` 強制 `vuln-verifier` + 人工批准 |

## 第一波實作清單

尚未開始實作。未來若統帥批准，建議順序如下：

1. 文件與契約：新增 `coding_task_v1` schema。
2. Gitea/GitHub 版本盤點：列出所有 Gitea repos、branches、tags、workflows、webhooks、secrets 名稱與 GitHub 對應目標。
3. Gitea Code Review：把 `scripts/ci_code_review.py` 報告轉成 `coding_task_v1`。
4. 儲存層：將 coding task 寫入既有 AI governance / AOL / artifact 位置。
5. Codex 半自動：產出可交給 Codex CLI / app 的 task prompt。
6. 權限閘門：`HIGH/CRITICAL` 必須人工批准，不得自動修補。
7. 測試證據：Codex patch 必須附測試指令、結果、diff summary。
8. Draft branch：只建立修補分支或 draft PR，不自動 merge。
9. 指標：記錄 task 數、成功率、重試率、token/credit、平均修補時間。
10. GitHub primary ADR：新增或修訂 ADR，明確取代 ADR-039 的長期方向與 rollback plan。

## 不在第一波做的事

- 不直接串 production deploy。
- 不自動合併 Codex patch。
- 不啟用 Codex API 自動長任務。
- 不讓 Claude Code 觸發 GitHub-hosted 高頻 workflow。
- 不自動修改 secrets、RBAC、NetworkPolicy、firewall、資料庫破壞性 migration。
- 不在完成 Gitea 全量版本轉移與 self-hosted runner 驗證前，把 GitHub 切成唯一主控。

## 參考來源

- [ADR-039: GitHub → Gitea CI/CD 遷移](/Users/ogt/awoooi/docs/adr/ADR-039-gitea-cicd-migration.md)
- [12-Agent 新遊戲規則](/Users/ogt/awoooi/docs/12-agent-game-rules.md)
- [Kali 資訊安全網藍圖](/Users/ogt/awoooi/docs/security/KALI-SECURITY-MESH-BLUEPRINT.md)
- [GitHub Actions billing](https://docs.github.com/en/billing/managing-billing-for-your-products/about-billing-for-github-actions)
- [OpenAI Codex cloud](https://platform.openai.com/docs/codex/overview)
- [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan%252525252525252525252525252525252525252525252525252525252528.pdf)
- [OpenAI API Pricing](https://openai.com/api/pricing/)
- [OpenAI Code generation / Codex models](https://platform.openai.com/docs/guides/code-generation)
- [NVIDIA Nemotron 3 family](https://nvidianews.nvidia.com/news/nvidia-debuts-nemotron-3-family-of-open-models)
- [NVIDIA Nemotron 3 Super](https://blogs.nvidia.com/blog/nemotron-3-super-agentic-ai/)
- [NVIDIA NeMo](https://www.nvidia.com/en-us/ai-data-science/products/nemo/)