Update: enrich gitea webhook article with story + practical process

docs-tech/gitea-webhook-ai-review/index.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 2
 title: ローカルGitea × Webhook連携で、AIとの開発をもっと楽にしよう！
-description: GiteaのIssue/PR WebhookとOpenClawを連携し、壊れにくい自動レビュー開発フローを構築する実践ガイド
+description: GiteaのIssue/PR WebhookとOpenClawを連携し、実運用で壊れにくく回す開発プロセスを構築する実践記録
 hide_table_of_contents: false
 displayed_sidebar: null
 ---
@@ -10,83 +10,117 @@ displayed_sidebar: null
 
 ## はじめに
 
-Issueを作ったらAIがレビューして、PRが来たらAIが最終チェックして、最後はmainに安全に反映する。
+「Issue を立てるだけで、AI がレビューして修正提案まで返してくれたら最高なのに…」
 
-この記事は、Gitea + OpenClaw 連携を **実運用で壊れにくく回すための最新版プロセス** をまとめたものです。
+そんな願望から始めたのが、**Gitea Webhook → OpenClaw** の自動レビュー連携です。
+最初は「Issue 作成でAIを呼べればOK」と思っていたのですが、実運用に入るとすぐに壁に当たりました。
 
-## できること
+- `EOF` でWebhookが落ちる
+- PRを投げても `OK (ignored event)`
+- ブリッジの別機能改修で本線が壊れる
+- Gitが苦手なメンバーがブランチ運用で詰まる
 
-- Issue作成で AI レビュー/修正タスクを起動
-- Pull Request 作成でも AI レビューを起動
-- ブランチ運用・反映手順をテンプレ化して Git 不慣れでも回せる
-- ブリッジを systemd 常駐して安定運用
+この記事は、その失敗込みで最終的に安定した **運用可能な形** をまとめたものです。
 
-## 最新アーキテクチャ
+## この記事でわかること
+
+- Issue / PR の両方をトリガーにする Webhook 設計
+- bridge.py の実装で絶対外せない防御ポイント
+- systemd での安定運用
+- 壊れにくいブランチ運用（Git弱者向け手順を毎回添える）
+- 機能混在で壊れたときの再発防止（リポジトリ分離）
+
+## 全体構成（最新版）
 
 ```
 ┌─────────┐     Webhook (issues / pull_request)   ┌────────────────────┐
 │  Gitea   │ ────────────────────────────────────→ │ gitea-webhook-bridge │
-└─────────┘                                        │   (bridge.py)      │
+└─────────┘                                        │      bridge.py      │
                                                     └────────┬──────────┘
                                                              │
-                                                     openclaw agent
+                                                      openclaw agent
                                                              │
-                                                      code-review-loop
+                                                    code-review-loop
                                                              │
-                                                         Issueコメント
+                                                  Issue/PRコメントで返却
 ```
 
-## Webhook対象イベント
+## なぜ最初に壊れたのか（実話）
 
-現在の推奨設定は以下です。
+### 1) `EOF` でDelivery失敗
 
-- `issues`:
+原因は、Gitea側ではなく受信側でした。`do_POST` 内で例外が出ているのに、HTTPレスポンスを返さず接続が閉じる。
+Giteaから見ると `Post ... EOF` です。
+
+**対策:**
+- `do_POST` 全体を `try/except` で囲む
+- 例外時も `500` を必ず返す
+
+### 2) PRが無視される
+
+Issue対応だけ先に作ると、PRイベントは素通りします。
+その結果 `OK (ignored event)`。
+
+**対策:**
+- `issues` だけでなく `pull_request` も受理
+- `opened / reopened / synchronize` を最低限処理
+
+### 3) 別用途改修でブリッジが壊れる
+
+Discord通知などを同じブリッジに混ぜると、修正の副作用でGitea連携が壊れやすい。
+
+**対策:**
+- 役割ごとにリポジトリを分離
+  - `gitea-webhook-bridge`
+  - `discord-notify-bridge`
+- systemdサービスも分離
+
+## bridge.py の実装指針
+
+### 受けるイベント
+
+- `issues`
   - `opened`
-- `pull_request`:
+- `pull_request`
   - `opened`
   - `reopened`
   - `synchronize`
 
-`pull_request` 未対応だと、PRで `OK (ignored event)` になって自動レビューされません。
+### 最低限の処理順
 
-## bridge.py の要点
+1. 署名検証（`X-Gitea-Signature`）
+2. イベント種別チェック
+3. アクションチェック
+4. タスク本文を整形
+5. `openclaw agent` を非同期起動
+6. すぐに `200 OK` を返す
 
-- `X-Gitea-Signature` で HMAC 検証
-- `/webhook/gitea` で `issues` / `pull_request` を分岐処理
-- `openclaw agent` を非同期で起動
-- Webhookハンドラで例外が起きても **必ずHTTPレスポンスを返す**（EOF対策）
+### 署名検証は必須
 
 :::warning
-`EOF` が出る場合、受信サーバーが例外落ちしてレスポンス返せていないケースが多いです。
-`do_POST` 全体を `try/except` で保護し、`500` を返すようにしてください。
+ローカルネットワークでも署名検証は省略しない方が安全です。
+Webhook URLを知っているだけで叩ける状態は避けましょう。
 :::
 
-## 運用で効いたルール
+## Gitea側の設定
 
-### 1) ブランチ命名を固定
+### `ALLOWED_HOST_LIST` を忘れない
 
-- `fix/issue-<番号>-<要約>`
-- `feat/issue-<番号>-<要約>`
-- `docs/issue-<番号>-<要約>`
+```ini title="app.ini"
+[webhook]
+ALLOWED_HOST_LIST = private
+```
 
-### 2) Issueコメントに毎回添える3点
+これを忘れると、プライベートIP向けWebhookがブロックされます。
 
-- ブランチ切替コマンド
-- 検証コマンド
-- main へのマージコマンド
+### Webhookの基本値
 
-### 3) 機能を分離する
+- URL: `http://<bridge-host>:9876/webhook/gitea`
+- Content-Type: `application/json`
+- Secret: bridgeと一致
+- Trigger: `issues`, `pull_request`
 
-Webhook橋渡しを1つに詰め込みすぎると壊れます。
-
-実運用では以下のように分離すると安全です。
-
-- `gitea-webhook-bridge`（Issue/PR連携専用）
-- `discord-notify-bridge`（通知専用）
-
-サービスも別systemdに分離。
-
-## systemd の基本
+## systemd常駐（再起動に強い構成）
 
 ```ini title="/etc/systemd/system/gitea-webhook-bridge.service"
 [Unit]
@@ -112,39 +146,47 @@ sudo systemctl enable --now gitea-webhook-bridge
 sudo systemctl status gitea-webhook-bridge
 ```
 
-## Gitea 側チェックポイント
+## 開発プロセス（ここが本体）
 
-### `ALLOWED_HOST_LIST`（必須）
+単にWebhookを動かすだけだと、チーム運用では破綻します。
+最終的に安定したのは、以下のルールを固定したからです。
 
-```ini title="app.ini"
-[webhook]
-ALLOWED_HOST_LIST = private
-```
+### ルール1: ブランチ命名を固定
 
-### Webhook設定
+- `fix/issue-<番号>-<要約>`
+- `feat/issue-<番号>-<要約>`
+- `docs/issue-<番号>-<要約>`
 
-- URL: `http://<bridge-host>:9876/webhook/gitea`
-- Content-Type: `application/json`
-- Secret: bridge側と一致
-- トリガー: `issues`, `pull_request`
+### ルール2: Issueコメントに毎回「3点セット」
 
-## Git弱者向けテンプレ（そのまま使える）
+- ブランチ切替手順
+- 検証コマンド
+- mainへの反映手順
 
-### 作業ブランチへ切替
+これを毎回書くだけで、Gitに不慣れな人の詰まりが激減しました。
+
+### ルール3: PRイベントでも同じフローでレビュー
+
+IssueだけでなくPRでもレビューが走ると、
+「修正は出たが最終反映前チェックが抜ける」問題を防げます。
+
+## Git弱者向けテンプレ（コピペ用）
+
+### 1) 修正ブランチへ切替
 
 ```bash
 git fetch origin
 git switch fix/issue-123-xxx
-# 古いGit: git checkout fix/issue-123-xxx
+# 古いgitなら: git checkout fix/issue-123-xxx
 ```
 
-### 検証
+### 2) 検証
 
 ```bash
 python3 -m py_compile src/*.py app/*.py
 ```
 
-### mainへ反映
+### 3) mainへ反映
 
 ```bash
 git switch main
@@ -153,16 +195,31 @@ git merge --no-ff fix/issue-123-xxx
 git push origin main
 ```
 
+### 4) 後片付け（任意）
+
+```bash
+git branch -d fix/issue-123-xxx
+git push origin --delete fix/issue-123-xxx
+```
+
+## 今後の拡張
+
+- ラベル付きIssueのみ処理（`ai-review` など）
+- PRへの自動レビューコメント整形
+- 失敗時の自動再試行と通知
+- レビュー結果のダッシュボード化
+
 ## まとめ
 
-Gitea × OpenClaw 連携は、実装より運用設計が重要です。
+Gitea × OpenClaw 連携は、作るだけなら簡単です。
+でも、**壊れずに回す**には運用設計がすべてでした。
 
-- イベント対応（Issue + PR）
-- 例外時のHTTP応答保証
-- ブランチ/コメントテンプレの固定
-- 機能分離（リポジトリ・サービス）
+- Issue + PR イベント対応
+- EOF対策（例外時も必ず応答）
+- ブリッジの責務分離
+- ブランチ/手順テンプレの固定
 
-ここを押さえると、連携はかなり安定します。
+この4点を押さえると、AI連携は実務で使えるレベルまで安定します。
 
 ---
 *この記事は2026年2月時点の情報です。*