From e007429a3db80f81b7f767a3894d5d335c8041aa Mon Sep 17 00:00:00 2001 From: koide Date: Fri, 27 Feb 2026 03:43:57 +0000 Subject: [PATCH] Update: enrich gitea webhook article with story + practical process --- docs-tech/gitea-webhook-ai-review/index.md | 191 +++++++++++++-------- 1 file changed, 124 insertions(+), 67 deletions(-) diff --git a/docs-tech/gitea-webhook-ai-review/index.md b/docs-tech/gitea-webhook-ai-review/index.md index 4afa079..d3b1cdc 100644 --- a/docs-tech/gitea-webhook-ai-review/index.md +++ b/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://: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://: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月時点の情報です。*