# ADR-029: CI/CD AI 整合架構 (Phase 13.1)

| 項目 | 內容 |
|------|------|
| **狀態** | ✅ 已採用 |
| **日期** | 2026-03-26 |
| **決策者** | 首席架構師 + 統帥 |
| **Phase** | Phase 13.1 |

## 背景

Phase 13.1 需要將 GitHub CI/CD 事件整合到 AWOOOI + OpenClaw 系統，實現：
1. PR/Push 自動代碼審查
2. CI 失敗自動診斷
3. 風險分級自動修復

## 決策

採用 **事件驅動 + 風險分級** 架構：

```
GitHub Events
    │
    ├─ pull_request ──→ OpenClaw Code Review
    ├─ push ──────────→ OpenClaw Push Review
    └─ workflow_run ──→ CI Failure Diagnosis
                            │
                            ▼
                    ┌─────────────────┐
                    │ CIAutoRepair    │
                    │ Service         │
                    └─────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    ┌───────────┐   ┌───────────┐   ┌───────────┐
    │ LOW       │   │ MEDIUM    │   │ HIGH/CRIT │
    │ 自動執行   │   │ TG 確認   │   │ Approval  │
    └───────────┘   └───────────┘   └───────────┘
```

## 架構元件

### 1. GitHub Webhook Handler (github_webhook.py)

```python
# 支援事件類型
- pull_request: opened, synchronize, reopened
- push: refs/heads/main, refs/heads/master
- workflow_run: completed + failure/timed_out

# 安全機制
- HMAC-SHA256 簽名驗證 (X-Hub-Signature-256)
- 倉庫白名單 (GITHUB_ALLOWED_REPOS)
- Fail-closed 策略
```

### 2. CI Auto-Repair Service (ci_auto_repair.py)

```python
# 風險等級決策
class ExecutionDecision(Enum):
    AUTO_EXECUTE = "auto_execute"        # LOW 風險
    TELEGRAM_CONFIRM = "telegram_confirm" # MEDIUM 風險
    APPROVAL_REQUIRED = "approval_required" # HIGH 風險
    BLOCKED = "blocked"                   # CRITICAL

# 整合 Phase 13.3 智能路由
- Intent Classifier: 判斷修復意圖
- Complexity Scorer: 評估複雜度
```

### 3. SignOz Log Query (signoz_client.py)

```python
# 新增方法
- get_logs(): 查詢日誌 (服務/級別/搜尋)
- get_error_logs_summary(): 錯誤摘要統計

# MCP Tools
- query_logs: 通用日誌查詢
- error_logs_summary: 錯誤摘要
```

## 資料流

```
1. GitHub Webhook → AWOOOI API
   ├─ HMAC 驗證
   └─ 倉庫白名單檢查

2. 背景任務處理
   ├─ 收集失敗資訊
   ├─ 查詢 SignOz 日誌
   └─ 呼叫 OpenClaw 診斷

3. 風險評估
   ├─ Intent Classification
   ├─ Complexity Scoring
   └─ 生成修復建議

4. 執行決策
   ├─ LOW → 自動執行
   ├─ MEDIUM → Telegram 快速確認
   ├─ HIGH → 建立 Approval
   └─ CRITICAL → 禁止自動修復

5. 結果通知
   ├─ Redis 儲存 (7 天 TTL)
   └─ Telegram 通知
```

## 錯誤類型映射

| 錯誤類型 | 修復動作 | 風險等級 |
|---------|---------|---------|
| build | clear_cache, fix_dependency | LOW-MEDIUM |
| test | retry_workflow, fix_config | LOW-MEDIUM |
| lint | retry_workflow | LOW |
| deploy | rollback_commit, fix_config | HIGH |
| timeout | restart_runner, scale_resource | LOW-MEDIUM |
| runner | restart_runner | LOW |

## 配置

```python
# config.py
GITHUB_WEBHOOK_SECRET: str  # Webhook 簽名密鑰
GITHUB_ALLOWED_REPOS: str   # 白名單倉庫

# 環境變數 (K8s Secret)
GITHUB_WEBHOOK_SECRET=<secret>
GITHUB_ALLOWED_REPOS=owner/repo1,owner/repo2
```

## 後果

### 正面
- CI 失敗自動診斷，減少人工介入
- 風險分級保護，防止誤操作
- 整合智能路由，決策更精準

### 負面
- OpenClaw 依賴 (需要 AI 服務可用)
- 額外延遲 (診斷需要 AI 處理時間)

## 相關文件

- ADR-023: Smart Routing Architecture
- ADR-024: API Layer Architecture
- Skill 07: Tool Integration Expert
- Skill 08: Model Router Expert
- `feedback_cicd_aiops_patterns.md`