775 lines
24 KiB
Markdown
775 lines
24 KiB
Markdown
# Gitea Webhook Migration Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 將 GitHub Webhook 整合（Phase 13.1）遷移至 Gitea Webhook，讓 Gitea PR/Push 事件能觸發 OpenClaw AI 代碼審查。
|
||
|
||
**Architecture:** 最少改動策略 — Gitea 與 GitHub 的 payload 欄位幾乎相同，差異只在 HTTP header 名稱。重命名檔案、替換 Header 常數、移除 `workflow_run` handler，業務邏輯層（OpenClaw 呼叫、Redis 儲存、Telegram 通知、Approval 建立）完全不動。
|
||
|
||
**Tech Stack:** FastAPI, Python 3.11, pytest-asyncio, httpx ASGITransport, K8s Secrets, Gitea Webhook
|
||
|
||
---
|
||
|
||
## File Map
|
||
|
||
| 動作 | 路徑 |
|
||
|------|------|
|
||
| 新增 | `apps/api/src/api/v1/gitea_webhook.py` |
|
||
| 新增 | `apps/api/src/services/gitea_webhook_service.py` |
|
||
| 修改 | `apps/api/src/main.py` |
|
||
| 修改 | `apps/api/src/core/config.py` |
|
||
| 修改 | `k8s/awoooi-prod/03-secrets.yaml` |
|
||
| 修改 | `.gitea/workflows/cd.yaml` |
|
||
| 新增 | `apps/api/tests/test_gitea_webhook.py` |
|
||
| 修改 | `apps/api/tests/conftest.py` |
|
||
| 刪除 | `apps/api/src/api/v1/github_webhook.py` |
|
||
| 刪除 | `apps/api/src/services/github_webhook_service.py` |
|
||
| 刪除 | `apps/api/tests/test_github_webhook.py` |
|
||
| 新增 | `docs/adr/ADR-059-gitea-webhook-integration.md` |
|
||
|
||
---
|
||
|
||
## Task 1: Config 層 — 替換 GITHUB_ → GITEA_ 環境變數
|
||
|
||
**Files:**
|
||
- Modify: `apps/api/src/core/config.py:490-505`
|
||
|
||
- [ ] **Step 1: 讀取現有 config 確認位置**
|
||
|
||
```bash
|
||
grep -n "GITHUB_WEBHOOK_SECRET\|GITHUB_ALLOWED_REPOS\|get_github_allowed" apps/api/src/core/config.py
|
||
```
|
||
|
||
Expected output 類似:
|
||
```
|
||
490: GITHUB_WEBHOOK_SECRET: str = Field(
|
||
494: GITHUB_ALLOWED_REPOS: str = Field(
|
||
501: raw = self.GITHUB_ALLOWED_REPOS
|
||
```
|
||
|
||
- [ ] **Step 2: 替換 config.py 中的 GITHUB_ 欄位**
|
||
|
||
將 `apps/api/src/core/config.py` 中這段：
|
||
|
||
```python
|
||
GITHUB_WEBHOOK_SECRET: str = Field(
|
||
default="",
|
||
description="GitHub Webhook secret for signature verification (X-Hub-Signature-256)",
|
||
)
|
||
GITHUB_ALLOWED_REPOS: str = Field(
|
||
default="",
|
||
description="Comma-separated list of allowed repositories (e.g., 'owner/repo1,owner/repo2')",
|
||
)
|
||
|
||
def get_github_allowed_repos(self) -> list[str]:
|
||
"""Parse comma-separated allowed repos to list"""
|
||
raw = self.GITHUB_ALLOWED_REPOS
|
||
if not raw or not raw.strip():
|
||
return []
|
||
return [repo.strip() for repo in raw.split(",") if repo.strip()]
|
||
```
|
||
|
||
改為：
|
||
|
||
```python
|
||
GITEA_WEBHOOK_SECRET: str = Field(
|
||
default="",
|
||
description="Gitea Webhook secret for HMAC-SHA256 signature verification (X-Gitea-Signature)",
|
||
)
|
||
GITEA_ALLOWED_REPOS: str = Field(
|
||
default="wooo/awoooi",
|
||
description="Comma-separated list of allowed Gitea repositories (e.g., 'wooo/awoooi')",
|
||
)
|
||
|
||
def get_gitea_allowed_repos(self) -> list[str]:
|
||
"""Parse comma-separated allowed repos to list"""
|
||
# 2026-04-05 Claude Code (ADR-059): GitHub → Gitea webhook 遷移
|
||
raw = self.GITEA_ALLOWED_REPOS
|
||
if not raw or not raw.strip():
|
||
return []
|
||
return [repo.strip() for repo in raw.split(",") if repo.strip()]
|
||
```
|
||
|
||
- [ ] **Step 3: 驗證 config 語法正確**
|
||
|
||
```bash
|
||
cd apps/api && python3.11 -c "from src.core.config import settings; print('GITEA_WEBHOOK_SECRET:', repr(settings.GITEA_WEBHOOK_SECRET)); print('GITEA_ALLOWED_REPOS:', repr(settings.GITEA_ALLOWED_REPOS))"
|
||
```
|
||
|
||
Expected:
|
||
```
|
||
GITEA_WEBHOOK_SECRET: ''
|
||
GITEA_ALLOWED_REPOS: 'wooo/awoooi'
|
||
```
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add apps/api/src/core/config.py
|
||
git commit -m "refactor(config): GITHUB_WEBHOOK_SECRET → GITEA_WEBHOOK_SECRET (ADR-059)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: Service 層 — 建立 gitea_webhook_service.py
|
||
|
||
**Files:**
|
||
- Create: `apps/api/src/services/gitea_webhook_service.py`
|
||
|
||
這個 task 從 `github_webhook_service.py` 複製並修改：
|
||
- class 名稱 `GitHub*` → `Gitea*`
|
||
- Redis key prefix `github_review:` → `gitea_review:`
|
||
- Telegram 訊息中 `GITHUB CODE REVIEW` → `GITEA CODE REVIEW`
|
||
- 移除 `CIFailureDiagnosis` class、`_call_openclaw_ci_diagnosis()`、`_send_ci_failure_telegram_alert()`、`_create_ci_failure_approval()`、`diagnose_ci_failure()` 整個 method
|
||
- 所有 payload 存取改用 `.get()` chain（防禦性解析）
|
||
|
||
- [ ] **Step 1: 複製並重命名**
|
||
|
||
```bash
|
||
cp apps/api/src/services/github_webhook_service.py apps/api/src/services/gitea_webhook_service.py
|
||
```
|
||
|
||
- [ ] **Step 2: 批次替換 class/常數名稱**
|
||
|
||
```bash
|
||
cd apps/api/src/services
|
||
# 替換 class 名稱和常數
|
||
sed -i \
|
||
-e 's/GITHUB_REVIEW_TTL_SECONDS/GITEA_REVIEW_TTL_SECONDS/g' \
|
||
-e 's/IGitHubReviewRepository/IGiteaReviewRepository/g' \
|
||
-e 's/GitHubReviewRedisRepository/GiteaReviewRedisRepository/g' \
|
||
-e 's/GitHubWebhookService/GiteaWebhookService/g' \
|
||
-e 's/get_github_webhook_service/get_gitea_webhook_service/g' \
|
||
-e 's/github_review:/gitea_review:/g' \
|
||
-e 's/GITHUB CODE REVIEW/GITEA CODE REVIEW/g' \
|
||
-e 's/github-webhook/gitea-webhook/g' \
|
||
gitea_webhook_service.py
|
||
```
|
||
|
||
- [ ] **Step 3: 更新 config 存取（settings.GITHUB_ → settings.GITEA_）**
|
||
|
||
```bash
|
||
sed -i \
|
||
-e 's/settings\.GITHUB_WEBHOOK_SECRET/settings.GITEA_WEBHOOK_SECRET/g' \
|
||
-e 's/settings\.GITHUB_ALLOWED_REPOS/settings.GITEA_ALLOWED_REPOS/g' \
|
||
-e 's/settings\.get_github_allowed_repos/settings.get_gitea_allowed_repos/g' \
|
||
apps/api/src/services/gitea_webhook_service.py
|
||
```
|
||
|
||
- [ ] **Step 4: 移除 CI 診斷相關程式碼**
|
||
|
||
手動編輯 `apps/api/src/services/gitea_webhook_service.py`，刪除以下區塊：
|
||
|
||
1. `class CIFailureDiagnosis(BaseModel):` 整個 class（約 51-67 行附近）
|
||
2. `async def _call_openclaw_ci_diagnosis(self, ...)` 整個 method（約 268-320 行附近）
|
||
3. `async def _send_ci_failure_telegram_alert(self, ...)` 整個 method（約 448-548 行附近）
|
||
4. `async def _create_ci_failure_approval(self, ...)` 整個 method（約 633-719 行附近）
|
||
5. `async def diagnose_ci_failure(self, ...)` 整個 method（約 908-1042 行附近）
|
||
|
||
確認方式：
|
||
```bash
|
||
grep -n "ci_failure\|CIFailure\|diagnose_ci\|workflow_run" apps/api/src/services/gitea_webhook_service.py
|
||
```
|
||
Expected: 無輸出（全部移除）
|
||
|
||
- [ ] **Step 5: 更新檔案 docstring 和版本資訊**
|
||
|
||
在 `gitea_webhook_service.py` 頂部 docstring 改為：
|
||
|
||
```python
|
||
"""
|
||
AWOOOI API - Gitea Webhook Service
|
||
====================================
|
||
ADR-059: GitHub → Gitea Webhook 遷移
|
||
|
||
整合流程:
|
||
1. Gitea Webhook (PR/Push) → AWOOOI API
|
||
2. HMAC-SHA256 簽章驗證 (X-Gitea-Signature)
|
||
3. 解析 PR diff / Push commits
|
||
4. 呼叫 OpenClaw 進行 AI 代碼審查
|
||
5. 儲存審查結果到 Redis
|
||
6. 發送 Telegram 通知
|
||
7. (可選) 建立 Approval 等待人工確認
|
||
|
||
支援事件:
|
||
- pull_request: PR 代碼審查
|
||
- push: 主分支推送審查
|
||
|
||
版本: v1.0
|
||
最後修改: 2026-04-05 (台北時區)
|
||
修改者: Claude Code (ADR-059 GitHub → Gitea 遷移)
|
||
"""
|
||
```
|
||
|
||
- [ ] **Step 6: 審查所有 payload .get() 防禦性存取**
|
||
|
||
搜尋所有直接 key access 並改為 `.get()` chain：
|
||
|
||
```bash
|
||
grep -n 'payload\["' apps/api/src/services/gitea_webhook_service.py | head -20
|
||
```
|
||
|
||
對每個直接存取（`payload["key"]`）改為 `payload.get("key", default)`。
|
||
重要位置包含：
|
||
- `review_pull_request()` 中存取 `pull_request`、`repository`、`sender` 欄位
|
||
- `review_push()` 中存取 `commits`、`repository`、`ref` 欄位
|
||
|
||
範例修改：
|
||
```python
|
||
# ❌ 舊
|
||
repo_name = payload["repository"]["full_name"]
|
||
|
||
# ✅ 新
|
||
repo_name = payload.get("repository", {}).get("full_name", "")
|
||
```
|
||
|
||
- [ ] **Step 7: 語法驗證**
|
||
|
||
```bash
|
||
cd apps/api && python3.11 -c "from src.services.gitea_webhook_service import get_gitea_webhook_service; print('✅ import OK')"
|
||
```
|
||
|
||
Expected: `✅ import OK`
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add apps/api/src/services/gitea_webhook_service.py
|
||
git commit -m "feat(service): 新增 GiteaWebhookService (ADR-059，移除 CI 診斷)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: Router 層 — 建立 gitea_webhook.py
|
||
|
||
**Files:**
|
||
- Create: `apps/api/src/api/v1/gitea_webhook.py`
|
||
|
||
從 `github_webhook.py` 複製並修改：
|
||
- Header 常數：`X-GitHub-Event` → `X-Gitea-Event`、`X-Hub-Signature-256` → `X-Gitea-Signature`
|
||
- Router prefix：`/webhooks/github` → `/webhooks/gitea`
|
||
- 移除 `handle_workflow_run()` 和相關 Pydantic models (`GitHubWorkflowRun`, `GitHubWorkflowJob`)
|
||
- 所有 `GitHub*` class → `Gitea*`
|
||
- import 改為 `gitea_webhook_service`
|
||
|
||
- [ ] **Step 1: 複製並重命名**
|
||
|
||
```bash
|
||
cp apps/api/src/api/v1/github_webhook.py apps/api/src/api/v1/gitea_webhook.py
|
||
```
|
||
|
||
- [ ] **Step 2: 批次替換 header 名稱和 class 名稱**
|
||
|
||
```bash
|
||
sed -i \
|
||
-e 's/X-GitHub-Event/X-Gitea-Event/g' \
|
||
-e 's/X-Hub-Signature-256/X-Gitea-Signature/g' \
|
||
-e 's/X-GitHub-Delivery/X-Gitea-Delivery/g' \
|
||
-e 's/x_hub_signature_256/x_gitea_signature/g' \
|
||
-e 's/x_github_event/x_gitea_event/g' \
|
||
-e 's/x_github_delivery/x_gitea_delivery/g' \
|
||
-e 's/GitHubUser/GiteaUser/g' \
|
||
-e 's/GitHubRepository/GiteaRepository/g' \
|
||
-e 's/GitHubPullRequest/GiteaPullRequest/g' \
|
||
-e 's/GitHubCommit/GiteaCommit/g' \
|
||
-e 's/GitHubWebhookPayload/GiteaWebhookPayload/g' \
|
||
-e 's/GitHubWebhookResponse/GiteaWebhookResponse/g' \
|
||
-e 's/GitHubSignatureError/GiteaSignatureError/g' \
|
||
-e 's/verify_github_signature/verify_gitea_signature/g' \
|
||
-e 's/verify_allowed_repo/verify_gitea_allowed_repo/g' \
|
||
-e 's/github_webhook_service/gitea_webhook_service/g' \
|
||
-e 's/get_github_webhook_service/get_gitea_webhook_service/g' \
|
||
-e 's/GitHubWebhookService/GiteaWebhookService/g' \
|
||
apps/api/src/api/v1/gitea_webhook.py
|
||
```
|
||
|
||
- [ ] **Step 3: 替換 router prefix 和 config 存取**
|
||
|
||
```bash
|
||
sed -i \
|
||
-e 's|prefix="/webhooks/github"|prefix="/webhooks/gitea"|g' \
|
||
-e 's/tags=\["GitHub Webhook"\]/tags=["Gitea Webhook"]/g' \
|
||
-e 's/settings\.GITHUB_WEBHOOK_SECRET/settings.GITEA_WEBHOOK_SECRET/g' \
|
||
-e 's/settings\.get_github_allowed_repos/settings.get_gitea_allowed_repos/g' \
|
||
apps/api/src/api/v1/gitea_webhook.py
|
||
```
|
||
|
||
- [ ] **Step 4: 移除 workflow_run 相關程式碼**
|
||
|
||
手動編輯 `apps/api/src/api/v1/gitea_webhook.py`，刪除以下區塊：
|
||
|
||
1. `class GitHubWorkflowRun(BaseModel):` 整個 class
|
||
2. `class GitHubWorkflowJob(BaseModel):` 整個 class（若存在）
|
||
3. `async def handle_workflow_run(...)` 整個 function
|
||
4. 主 handler `handle_gitea_webhook()` 中 `workflow_run` 的 dispatch branch：
|
||
```python
|
||
elif event_type == "workflow_run":
|
||
return await handle_workflow_run(payload)
|
||
```
|
||
|
||
確認移除：
|
||
```bash
|
||
grep -n "workflow_run\|WorkflowRun\|WorkflowJob" apps/api/src/api/v1/gitea_webhook.py
|
||
```
|
||
Expected: 無輸出
|
||
|
||
- [ ] **Step 5: 更新 docstring**
|
||
|
||
在 `gitea_webhook.py` 頂部 docstring 改為：
|
||
|
||
```python
|
||
"""
|
||
AWOOOI API - Gitea Webhook Handler
|
||
====================================
|
||
ADR-059: GitHub → Gitea Webhook 遷移
|
||
|
||
整合流程:
|
||
1. Gitea Webhook (PR/Push) → AWOOOI API
|
||
2. HMAC-SHA256 簽章驗證 (X-Gitea-Signature)
|
||
3. 解析 PR diff / Push commits
|
||
4. 呼叫 OpenClaw 進行 AI 代碼審查
|
||
5. 儲存審查結果到 Redis
|
||
6. 發送 Telegram 通知
|
||
7. (可選) 建立 Approval 等待人工確認
|
||
|
||
支援事件:
|
||
- pull_request: PR 代碼審查 (opened, synchronize, reopened)
|
||
- push: 主分支推送審查
|
||
- ping: 連線測試
|
||
|
||
安全要求:
|
||
- HMAC 簽章驗證 (X-Gitea-Signature)
|
||
- Webhook Secret 存放於 K8s Secret
|
||
- 倉庫白名單驗證
|
||
|
||
版本: v1.0
|
||
最後修改: 2026-04-05 (台北時區)
|
||
修改者: Claude Code (ADR-059 GitHub → Gitea 遷移)
|
||
"""
|
||
```
|
||
|
||
- [ ] **Step 6: 語法驗證**
|
||
|
||
```bash
|
||
cd apps/api && python3.11 -c "from src.api.v1.gitea_webhook import router; print('✅ router OK, prefix:', router.prefix)"
|
||
```
|
||
|
||
Expected: `✅ router OK, prefix: /webhooks/gitea`
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
git add apps/api/src/api/v1/gitea_webhook.py
|
||
git commit -m "feat(api): 新增 gitea_webhook router (ADR-059，Header 改 X-Gitea-*)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: main.py — 替換掛載
|
||
|
||
**Files:**
|
||
- Modify: `apps/api/src/main.py:43,467`
|
||
|
||
- [ ] **Step 1: 確認目前掛載位置**
|
||
|
||
```bash
|
||
grep -n "github_webhook" apps/api/src/main.py
|
||
```
|
||
|
||
Expected:
|
||
```
|
||
43: github_webhook as github_webhook_v1, # Phase 13.1: GitHub → OpenClaw
|
||
467: github_webhook_v1.router, prefix="/api/v1", tags=["GitHub Webhook"]
|
||
```
|
||
|
||
- [ ] **Step 2: 替換 import**
|
||
|
||
將 main.py 第 42-44 行附近的：
|
||
```python
|
||
from src.api.v1 import (
|
||
github_webhook as github_webhook_v1, # Phase 13.1: GitHub → OpenClaw
|
||
)
|
||
```
|
||
|
||
改為：
|
||
```python
|
||
from src.api.v1 import (
|
||
gitea_webhook as gitea_webhook_v1, # ADR-059: Gitea → OpenClaw (GitHub → Gitea 遷移)
|
||
)
|
||
```
|
||
|
||
- [ ] **Step 3: 替換 router 掛載**
|
||
|
||
將 main.py 中：
|
||
```python
|
||
app.include_router(
|
||
github_webhook_v1.router, prefix="/api/v1", tags=["GitHub Webhook"]
|
||
)
|
||
```
|
||
|
||
改為：
|
||
```python
|
||
app.include_router(
|
||
gitea_webhook_v1.router, prefix="/api/v1", tags=["Gitea Webhook"]
|
||
)
|
||
```
|
||
|
||
- [ ] **Step 4: 驗證 main.py 可 import**
|
||
|
||
```bash
|
||
cd apps/api && MOCK_MODE=true python3.11 -c "
|
||
import os; os.environ['MOCK_MODE']='true'; os.environ['DATABASE_URL']='postgresql+asyncpg://x:x@localhost/x'
|
||
from src.main import app
|
||
routes = [r.path for r in app.routes if hasattr(r, 'path')]
|
||
gitea_routes = [r for r in routes if 'gitea' in r]
|
||
print('Gitea routes:', gitea_routes)
|
||
github_routes = [r for r in routes if 'github' in r and 'gitea' not in r]
|
||
print('Leftover GitHub routes:', github_routes)
|
||
"
|
||
```
|
||
|
||
Expected:
|
||
```
|
||
Gitea routes: ['/api/v1/webhooks/gitea', '/api/v1/webhooks/gitea/reviews/{review_id}']
|
||
Leftover GitHub routes: []
|
||
```
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add apps/api/src/main.py
|
||
git commit -m "refactor(main): github_webhook → gitea_webhook router 掛載 (ADR-059)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: Tests — 建立 test_gitea_webhook.py
|
||
|
||
**Files:**
|
||
- Create: `apps/api/tests/test_gitea_webhook.py`
|
||
- Modify: `apps/api/tests/conftest.py`
|
||
|
||
- [ ] **Step 1: 更新 conftest.py**
|
||
|
||
將 `apps/api/tests/conftest.py` 中：
|
||
```python
|
||
os.environ.setdefault("GITHUB_WEBHOOK_SECRET", "test-secret-key-12345")
|
||
os.environ.setdefault("GITHUB_ALLOWED_REPOS", "test-owner/test-repo,wooo-ai/awoooi")
|
||
```
|
||
|
||
改為：
|
||
```python
|
||
os.environ.setdefault("GITEA_WEBHOOK_SECRET", "test-secret-key-12345")
|
||
os.environ.setdefault("GITEA_ALLOWED_REPOS", "test-owner/test-repo,wooo/awoooi")
|
||
```
|
||
|
||
- [ ] **Step 2: 建立 test_gitea_webhook.py**
|
||
|
||
```bash
|
||
cp apps/api/tests/test_github_webhook.py apps/api/tests/test_gitea_webhook.py
|
||
```
|
||
|
||
- [ ] **Step 3: 批次替換 header 和 import**
|
||
|
||
```bash
|
||
sed -i \
|
||
-e 's/X-Hub-Signature-256/X-Gitea-Signature/g' \
|
||
-e 's/X-GitHub-Event/X-Gitea-Event/g' \
|
||
-e 's/X-GitHub-Delivery/X-Gitea-Delivery/g' \
|
||
-e 's/from src\.api\.v1\.github_webhook import router as github_webhook_router/from src.api.v1.gitea_webhook import router as gitea_webhook_router/g' \
|
||
-e 's/github_webhook_router/gitea_webhook_router/g' \
|
||
-e 's|prefix="/api/v1"|prefix="/api/v1"|g' \
|
||
apps/api/tests/test_gitea_webhook.py
|
||
```
|
||
|
||
- [ ] **Step 4: 更新 app 建立**
|
||
|
||
在 `test_gitea_webhook.py` 找到：
|
||
```python
|
||
from src.api.v1.gitea_webhook import router as gitea_webhook_router
|
||
|
||
app = FastAPI()
|
||
app.include_router(gitea_webhook_router, prefix="/api/v1")
|
||
```
|
||
|
||
確認這兩行正確（sed 應已處理 import，確認 `include_router` 使用 `gitea_webhook_router`）。
|
||
|
||
- [ ] **Step 5: 執行測試，確認全部通過**
|
||
|
||
```bash
|
||
cd apps/api && source /opt/api-venv/bin/activate 2>/dev/null || python3.11 -m venv /tmp/test-venv && source /tmp/test-venv/bin/activate && pip install -q uv && uv pip install -q -e ".[dev]"
|
||
cd apps/api && python3.11 -m pytest tests/test_gitea_webhook.py -v
|
||
```
|
||
|
||
Expected: 8 tests PASSED：
|
||
```
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_missing_signature
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_invalid_signature
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_valid_signature
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_repo_not_in_whitelist
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_ping_event
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_push_event
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_push_non_default_branch
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_unsupported_event
|
||
PASSED tests/test_gitea_webhook.py::test_webhook_pr_unsupported_action
|
||
```
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add apps/api/tests/test_gitea_webhook.py apps/api/tests/conftest.py
|
||
git commit -m "test: test_gitea_webhook.py — 8 個測試覆蓋 HMAC/whitelist/events (ADR-059)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: 清除舊 GitHub 檔案
|
||
|
||
**Files:**
|
||
- Delete: `apps/api/src/api/v1/github_webhook.py`
|
||
- Delete: `apps/api/src/services/github_webhook_service.py`
|
||
- Delete: `apps/api/tests/test_github_webhook.py`
|
||
|
||
- [ ] **Step 1: 確認 github_webhook 已無 import**
|
||
|
||
```bash
|
||
grep -rn "github_webhook" apps/api/src/ apps/api/tests/ --include="*.py" | grep -v "__pycache__"
|
||
```
|
||
|
||
Expected: 無輸出（所有 reference 都已在前面步驟移除）
|
||
|
||
- [ ] **Step 2: 刪除舊檔案**
|
||
|
||
```bash
|
||
git rm apps/api/src/api/v1/github_webhook.py \
|
||
apps/api/src/services/github_webhook_service.py \
|
||
apps/api/tests/test_github_webhook.py
|
||
```
|
||
|
||
- [ ] **Step 3: 確認無孤兒 import**
|
||
|
||
```bash
|
||
cd apps/api && python3.11 -c "from src.main import app; print('✅ main import OK')"
|
||
```
|
||
|
||
Expected: `✅ main import OK`
|
||
|
||
- [ ] **Step 4: 執行完整測試確認無 regression**
|
||
|
||
```bash
|
||
cd apps/api && python3.11 -m pytest tests/ -v --tb=short -x \
|
||
--ignore=tests/integration \
|
||
--ignore=tests/test_anomaly_counter.py \
|
||
--ignore=tests/test_global_repair_cooldown.py \
|
||
--ignore=tests/test_redis_multisig.py \
|
||
--ignore=tests/test_model_regression.py \
|
||
--ignore=tests/test_prompt_validation.py \
|
||
2>&1 | tail -30
|
||
```
|
||
|
||
Expected: 全部 PASSED，無 FAILED
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git commit -m "chore: 移除舊 GitHub Webhook 檔案 (github_webhook.py / service / test) — ADR-059"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: K8s Secrets + CD Pipeline
|
||
|
||
**Files:**
|
||
- Modify: `k8s/awoooi-prod/03-secrets.yaml`
|
||
- Modify: `.gitea/workflows/cd.yaml`
|
||
|
||
- [ ] **Step 1: 更新 03-secrets.yaml**
|
||
|
||
在 `k8s/awoooi-prod/03-secrets.yaml` 找到 `GITHUB_WEBHOOK_SECRET`（若存在），改為 `GITEA_WEBHOOK_SECRET: "CHANGE_ME"`。
|
||
|
||
若不存在，在適當位置新增：
|
||
```yaml
|
||
GITEA_WEBHOOK_SECRET: "CHANGE_ME" # 2026-04-05 Claude Code (ADR-059): CD 自動注入
|
||
```
|
||
|
||
確認：
|
||
```bash
|
||
grep -n "GITEA_WEBHOOK_SECRET\|GITHUB_WEBHOOK_SECRET" k8s/awoooi-prod/03-secrets.yaml
|
||
```
|
||
|
||
Expected: 只看到 `GITEA_WEBHOOK_SECRET`，無 `GITHUB_WEBHOOK_SECRET`。
|
||
|
||
- [ ] **Step 2: 更新 cd.yaml Inject K8s Secrets step**
|
||
|
||
在 `.gitea/workflows/cd.yaml` 的 `Inject K8s Secrets` step（`SECRETS` heredoc 內），在現有注入區塊末尾（`echo "✅ 所有 Secrets 注入完成"` 之前）新增：
|
||
|
||
```bash
|
||
# ADR-059: Gitea Webhook Secret (PR/Push → OpenClaw 代碼審查)
|
||
if [ -n "${GITEA_WEBHOOK_SECRET}" ]; then
|
||
sudo kubectl patch secret awoooi-secrets -n awoooi-prod --type='json' -p='[
|
||
{"op":"add","path":"/data/GITEA_WEBHOOK_SECRET","value":"'"$(echo -n "${GITEA_WEBHOOK_SECRET}" | base64 -w 0)"'"}
|
||
]' && echo "✅ GITEA_WEBHOOK_SECRET 已注入" || echo "⚠️ GITEA_WEBHOOK_SECRET patch 失敗"
|
||
else
|
||
echo "⚠️ GITEA_WEBHOOK_SECRET 未設定，Gitea webhook 簽章驗證將跳過"
|
||
fi
|
||
```
|
||
|
||
同時在 step 的 `env:` 區塊新增：
|
||
```yaml
|
||
GITEA_WEBHOOK_SECRET: ${{ secrets.GITEA_WEBHOOK_SECRET }}
|
||
```
|
||
|
||
- [ ] **Step 3: 驗證 cd.yaml YAML 語法**
|
||
|
||
```bash
|
||
python3 -c "import yaml; yaml.safe_load(open('.gitea/workflows/cd.yaml')); print('✅ YAML OK')"
|
||
```
|
||
|
||
Expected: `✅ YAML OK`
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add k8s/awoooi-prod/03-secrets.yaml .gitea/workflows/cd.yaml
|
||
git commit -m "ops(k8s+cd): 新增 GITEA_WEBHOOK_SECRET 注入 (ADR-059)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 8: ADR 文件
|
||
|
||
**Files:**
|
||
- Create: `docs/adr/ADR-059-gitea-webhook-integration.md`
|
||
|
||
- [ ] **Step 1: 建立 ADR-059**
|
||
|
||
```bash
|
||
cat > docs/adr/ADR-059-gitea-webhook-integration.md << 'EOF'
|
||
# ADR-059: Gitea Webhook 整合 (GitHub → Gitea 遷移)
|
||
|
||
**日期**: 2026-04-05 (台北時區)
|
||
**狀態**: 已採用 (Adopted)
|
||
**決策者**: 統帥 + Claude Code
|
||
**關聯**: ADR-039 (Gitea CI/CD 遷移), ADR-029 (CI/CD AI 整合架構)
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
Phase 13.1 (ADR-029) 實作了 GitHub Webhook → OpenClaw AI 代碼審查整合。
|
||
但 ADR-039 已將 CI/CD 全面遷移至 Gitea，GitHub 只剩唯讀備份。
|
||
`GITHUB_WEBHOOK_SECRET` 從未注入 K8s Secrets，GitHub Webhook 功能處於死路狀態。
|
||
|
||
## 決策
|
||
|
||
將 GitHub Webhook 整合遷移至 Gitea Webhook。
|
||
廢棄 `workflow_run` CI 診斷功能（CD pipeline 已有 Telegram 通知覆蓋，重複無必要）。
|
||
|
||
## 遷移策略
|
||
|
||
**最少改動策略 (Minimal Viable Change)**
|
||
|
||
Gitea 與 GitHub 的 webhook payload 欄位幾乎相同，差異只在 HTTP header 名稱：
|
||
|
||
| 項目 | GitHub (廢棄) | Gitea (新) |
|
||
|------|-------------|-----------|
|
||
| 事件 Header | `X-GitHub-Event` | `X-Gitea-Event` |
|
||
| 簽章 Header | `X-Hub-Signature-256` | `X-Gitea-Signature` |
|
||
| 簽章格式 | `sha256=<hex>` | `sha256=<hex>` (相同) |
|
||
| Payload 欄位 | — | 幾乎相同 |
|
||
|
||
業務邏輯層（OpenClaw 呼叫、Redis 儲存、Telegram 通知、Approval 建立）完全不動。
|
||
|
||
## 支援事件
|
||
|
||
| 事件 | 狀態 |
|
||
|------|------|
|
||
| `pull_request` (opened/synchronize/reopened) | ✅ 遷移 |
|
||
| `push` (main/master) | ✅ 遷移 |
|
||
| `workflow_run` | ❌ 廢棄 |
|
||
| `ping` | ✅ 遷移 |
|
||
|
||
## 端點變更
|
||
|
||
```
|
||
舊: POST /api/v1/webhooks/github
|
||
新: POST /api/v1/webhooks/gitea
|
||
```
|
||
|
||
## 實作護欄
|
||
|
||
1. **防禦性 payload 解析**: 所有欄位存取使用 `.get()` chain
|
||
2. **Gitea UI Content-Type**: 必須選 `application/json`（非 `application/x-www-form-urlencoded`）
|
||
|
||
## 後果
|
||
|
||
- Gitea PR/Push 事件可觸發 OpenClaw AI 代碼審查
|
||
- 移除 `workflow_run` CI 診斷（由 CD pipeline TG 通知替代）
|
||
- `GITHUB_WEBHOOK_SECRET` K8s Secret 廢棄，改用 `GITEA_WEBHOOK_SECRET`
|
||
EOF
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add docs/adr/ADR-059-gitea-webhook-integration.md
|
||
git commit -m "docs(adr): ADR-059 Gitea Webhook 整合 (GitHub → Gitea 遷移)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 9: Push 到 Gitea + 部署後手動設定
|
||
|
||
- [ ] **Step 1: Push**
|
||
|
||
```bash
|
||
git push gitea main
|
||
```
|
||
|
||
- [ ] **Step 2: 確認 CI 通過**
|
||
|
||
觀察 Gitea Actions。`Run API Tests` step 應包含 `test_gitea_webhook.py` 的 9 個測試全部 PASSED。
|
||
|
||
- [ ] **Step 3: 在 Gitea UI 設定 Webhook（部署完成後）**
|
||
|
||
1. 進入 `http://192.168.0.110:3001/wooo/awoooi` → Settings → Webhooks → Add Webhook → **Gitea**
|
||
2. **Target URL**: `https://awoooi.wooo.work/api/v1/webhooks/gitea`
|
||
3. **HTTP Method**: POST
|
||
4. **Content Type**: `application/json` ← **必須，否則 FastAPI 無法解析**
|
||
5. **Secret**: 與 Gitea Actions Secret `GITEA_WEBHOOK_SECRET` 相同值
|
||
6. **Trigger On**: Pull Request events ✅ + Push events ✅
|
||
7. **Active**: ✅ 勾選
|
||
8. 點擊 "Test Delivery" 確認 ping 事件收到 202 回應
|
||
|
||
- [ ] **Step 4: 在 Gitea Actions 新增 Secret**
|
||
|
||
`http://192.168.0.110:3001/wooo/awoooi` → Settings → Actions → Secrets → 新增：
|
||
- Name: `GITEA_WEBHOOK_SECRET`
|
||
- Value: （統帥決定，與 Gitea UI Webhook Secret 相同）
|
||
|
||
---
|
||
|
||
## Self-Review
|
||
|
||
**Spec coverage check:**
|
||
|
||
| Spec 要求 | 對應 Task |
|
||
|-----------|-----------|
|
||
| `github_webhook.py` → `gitea_webhook.py` | Task 3 |
|
||
| `github_webhook_service.py` → `gitea_webhook_service.py` | Task 2 |
|
||
| `main.py` 更新 import + 路徑 | Task 4 |
|
||
| `config.py` GITHUB_ → GITEA_ | Task 1 |
|
||
| `03-secrets.yaml` 更新 | Task 7 |
|
||
| `cd.yaml` 注入 GITEA_WEBHOOK_SECRET | Task 7 |
|
||
| `conftest.py` env var 更新 | Task 5 |
|
||
| `test_gitea_webhook.py` | Task 5 |
|
||
| 舊 GitHub 檔案刪除 | Task 6 |
|
||
| ADR-059 | Task 8 |
|
||
| 防禦性 `.get()` 解析 | Task 2 Step 6 |
|
||
| Content-Type 警告文件 | Task 9 Step 3 |
|
||
| Gitea UI 設定步驟 | Task 9 Step 3 |
|
||
|
||
**Placeholder scan:** 無 TBD/TODO，所有步驟含完整程式碼或指令。
|
||
|
||
**Type consistency:** `GiteaWebhookService`、`get_gitea_webhook_service`、`gitea_webhook_router` 在 Task 2/3/4/5 命名一致。
|