1. 痛み分解：コードホスティングの Webhook は「ただの HTTP」ではない
(1) 署名とリプレイ：HMAC を検証する前に JSON を解くと、公開 Gateway に届く偽ペイロードでコメント投稿やラベル変更が走る。(2) 過剰スコープ：便利さで repo や広い api を渡すと、漏えい時の爆半径が組織全体になる。(3) 401 と 403：401 は身元（期限切れヘッダ、時刻ズレ）、403 は権限（ブランチ保護、インストール範囲、SSO）。混同すると ACL ではなく温度調整に時間を溶かす。(4) べき等性の嵐：synchronize や labeled が短時間に連打され、配送 ID が無いとスレが汚れレート制限が跳ねる。(5) launchd の継承差：対話シェルでは動くが再起動で 401、というのは移行記事と同系統の不具合である。
さらに脅威モデルを文書化しないチームは、公開コメント事故やラベル誤削除のあとでコントロールを後付けする。Webhook 面を本番境界として扱い、検証失敗率をメトリクス化し、毎夜カナリリポに合成イベントを流すと安全余裕が増える。
2. 身元表：GitHub App、細粒度 PAT、GitLab トークン
| 方式 | 向く場面 | 最小権限の考え方 |
|---|---|---|
| GitHub App | 複数リポ、ローテ可能なインストールトークン | イベント購読を必要最小限に。Issues/PR のサブ権限も本当に要る範囲だけ |
| 細粒度 PAT | 個人・小規模 PoC | リポ限定、短命 TTL、イベントフィルタを設定に固定 |
| GitLab Project Token / Bot | MR/Issue 自動化 | プロジェクト単位の api。シークレットに加え IP 許可が使えるなら併用 |
3. 五段階導入：OpenClaw へ受け入れ可能な経路
- 安定した HTTPS エンドポイント：開発はトンネルでも可。本番は固定ホスト名と TLS でシークレットローテを予測可能に。
- JSON より先に検証：
X-Hub-Signature-256や GitLab のトークンヘッダが失敗したら 401。未信頼ボディでエージェントを浪費しない。 - べき等キー：配送 UUID か event+action+SHA の合成で重複排除。
openedだけ副作用、synchronize毎に LLM を叩かない方針を明示。 - 秘密の注入経路：launchd の EnvironmentVariables や限定ストア。ワークスペース平文に置かない。
- 構造化ログ：event/action/リポ/PR 番号/検証結果/下流 HTTP ステータス。
openclaw doctorと二層で見る。
4. レビューに貼れる閾値（組織方針で再検証）
設計レビュー向けの目安：
- 署名なしの公開 Webhook は数時間〜数日でスキャンが付きやすい。検証失敗率のアラートを必須に。
- すべての
synchronizeでモデルを回すと、openedとreview_requestedだけに絞る場合よりコストが桁違いになりがち。フィルタは口頭ではなく設定ファイルへ。 - トークン失効・権限変更・ブランチ保護起因の 401/403 調査が週3 時間を超えるなら、GitHub App か固定出口 IP のリモート Mac を検討。
5. 401 / 403 / 429：バケツを先に決める
| 症状 | 先に見る場所 | 典型原因 |
|---|---|---|
| 401 で Authorization 欠落 | launchd と対話シェルの環境差 | plist 未注入、Keychain の非対話 ACL 失敗 |
| 403、ローカル curl は成功 | SSO、IP 制限、App インストール範囲 | 組織ポリシーで bot 主体が拒否される |
| 429 / secondary limit | リトライとバックオフ | べき等欠如でコメント嵐→スロットル |
| 200 だがエージェント無反応 | action フィルタと skill ルーティング | 購読イベント違い、MCP 配線ドリフト |
| 502 が断続 | ingress のアイドルタイムアウト | プロバイダ再送と競合。ハンドラは速く返し非同期処理へ |
切り分け時はシークレットを除いたヘッダとボディ先頭のハッシュだけをチケットに残す。
6. FAQ：fork PR、シークレット、二重 Gateway
Q：fork からの PR を自動化する？ 既定は拒否か強い隔離。どうしてもなら人間ゲート付きの読み取り要約に留める。
Q：GitLab 自前運用？ リバプロのタイムアウトとボディサイズ上限。巨大 diff で JSON が欠けると半壊パースになる。
Q：ノートとリモート Mac の二重 Gateway？ チャネルと同様に単一のアクティブ Gatewayを推奨。セッション競合を避ける。
Q：本番を汚さず試す？ サンドボックス組織、短命トークン、録画したペイロードのリプレイ。本番だけ手修正しない。
Q：サブモジュール URL が要る？ コメント用トークンと取得用資格情報を分離し、読み取りミラーのみに限定。
7. 深掘り：開発自動化はオペレーション設計が本体
2026 年の現実的な価値は、低リスクの繰り返しコミュニケーションを人から外すこと：PR オープン時チェックリスト、テンプレ欠落の注意、マイルストーンに沿ったラベル提案。難所は REST 呼び出しではなく監査境界：誰が bot として発言できるか、絶対に自動生成してはいけない文言、インシデント時に二分以内で delivery とツール呼び出しを突き合わせられるか。
MCP では「Git 全部」を汎用エージェントに渡さず、postIssueComment や addLabel のような狭いツール面でリポ許可リストと action 許可リストを内側で強制する。
GitHub と GitLab はヘッダとペイロード形状が異なる。薄いアダプタで pull_request.opened のような内部イベントへ正規化し、skill 側に if 分岐を散らさない。
ドラフト PR の ready 化、クローズと再オープンは短時間に連続する。PR 単位の小さな状態機で「ウェルカム済み」「静的サマリ済み」を保持し、単純な opened 一回きりに依存しない。
Issue の assigned 連打はソーシャルノイズになる。初回アサインか needs-triage→ready の遷移だけに絞り、返信は短くリンク中心に。
CI の巨大コールバックを PR 通知と同じキューに混ぜない。失敗時サマリ専用ルートに分離しコンテキストを守る。
リモート Apple Silicon Mac は固定ユーザー・固定出口・24/7という運用メリットがある代わりに、launchd・ログローテ・トークンローテを本番作業として扱う。
Webhook ハンドラはすぐ 200 を返して非同期処理。LLM を同期ブロックするとプロバイダ再送が重複配送に見え、べき等ストアが熱くないと壊れる。
ペイロードのスキーマドリフトは避けられない。未知 action は無視既定にし、フィクスチャで契約テストを回す。
企業向けには監査ログの不変性と破壊的操作の人間オーバーライドを説明資料に書く。
8. 観測性：三つのログ項目
配送 ID、検証結果、下流 API のステータスと request id を固定化。どれかが欠けると、セキュリティ事後分析かプラットフォーム照合ができない。
| 事故 | 最初に見る | 封じ込め |
|---|---|---|
| コメント・ラベル嵐 | べき等ヒット率と action 列 | ルーティング停止か読み取りログのみへ降格 |
| 資格情報疑い | 直近一時間の配送パターン | シークレットとトークンをローテ、スコープ再監査 |
| リモート Mac の間欠 401 | launchd と手動起動の環境 diff、時刻、Keychain | 移行チェックリストに plist を揃え、短命トークン自動更新を検討 |
9. 内部レビューの証跡パック
スクリーンショットに加え、Webhook 設定マニフェスト、スコープごとの業務理由表、三種類のサンプル delivery、ステージングで署名を再検証するリプレイ手順を添付。リプレイが無いチームは初週の実流量で崩れやすい。
ログの越境保存やメール・氏名を含むボディの保持日数など、データレジデンシ要件を明記する。
四半期ごとにシークレットローテ演習を行い、二重シークレット窓とアラートを実証する。
オンコール用に、インストールトークン再取得や直近十件の配送ダンプ（マスク済み）のコマンドを Runbook に固定する。
10. 締め：サーバレスも有効だが Mac Gateway 文脈の一貫性
(1) 汎用サーバレスの限界：OpenClaw Gateway やローカルツールチェーンと切り離すとデバッグ経路が分岐し、コールドスタートは長寿命セッションと相性が悪い。(2) リモート Apple Silicon の利点：launchd・Keychain・デプロイ手順が同一ドキュメント線上に乗る。(3) Linux VPS が向く場合：ステートレスな変換だけなら十分なこともあるが、デスクトップ級メディアや GPU パスが絡むと摩擦が戻る。(4) MACGPU：ノートを疑似 DC にせず、Webhook 入口と Gateway を低摩擦で常時稼働の Mac ノードに載せ替えたい場合はトップのプランを参照。