29-模块四-AI代码审核实战 第29讲-Git 工作流集成 - Webhook 触发 PR 评论 审核状态管理

模块四-AI代码审核实战 | 第29讲：Git 工作流集成 - Webhook 触发、PR 评论、审核状态管理

本讲目标：把 CodeSentinel 从「本地脚本」接入 GitHub/GitLab 的真实事件流；掌握 Webhook 验签、PR/MR diff 拉取、行内评论与摘要评论、提交状态（commit status/check）更新；实现平台适配层 GitPlatformAdapter 与 ReviewStatusManager 状态机；交付 FastAPI Webhook 端点与可测试的 httpx 客户端示例。本讲强调安全默认值：先验签，再执行业务。建议准备一枚测试仓库与 Personal Access Token 做联调。

---

开场：没有托管平台集成，审核只是「自言自语」

自动代码审核的最终用户不是机器，而是正在协作的人类工程师。工程师最常停留的工作界面，通常是 Pull Request 或 Merge Request 页面：他们在这里阅读 diff、回复评论、查看检查项是否通过、决定是否合并。若你的 CodeSentinel 只会在终端打印 findings，它就很难进入团队的「默认工作流」，最终会被边缘化为少数爱好者的玩具。

本讲解决的是平台化接入问题：当有人打开或更新 PR，托管平台向你推送事件；你验证这是平台发来的真实请求而不是伪造攻击；你用平台 API 拉回可审核的变更内容；你把审核结果以评论与状态的形式写回 PR，让合并门槛可以依赖这些信号。你会同时看到 GitHub 与 GitLab 在概念上高度相似、在细节上处处不同：事件名不同、鉴权不同、评论 API 不同、状态检查字段不同。CodeSentinel 用适配器隔离差异，用状态机管理审核生命周期，避免把 if/else 平台分支写满业务核心。

完成本讲后，你应能向团队说明：Webhook 为什么是推送模型、为什么必须验签、以及如何把「pending → running → success/failure」映射到研发可理解的合并策略。下面先给出端到端事件流，再展开安全、API 与完整 Python 实现。

在工程组织层面，本讲还回答一个关键问题：平台集成要不要做在审核核心逻辑里？ 答案是不要。集成层负责「外部世界如何进来、结果如何出去」，审核核心负责「给定变更内容如何判定」。边界清晰后，你可以把同一套审核核心接到 GitHub、GitLab、Gerrit，甚至接到内部代码托管；也可以把 webhook 暂时替换为「CLI 手动触发」而不改规则引擎。很多团队失败的原因是把这些层搅在一起，最后任何平台字段变更都会牵动规则代码，维护成本指数上升。

此外，你要建立对「失败模式」的共同语言：验签失败、API 429、权限不足、评论定位非法、以及任务重试导致的重复评论，分别对应不同的运维动作。把失败分桶后，On-call 才不会每次靠猜。下面先给出端到端事件流，再展开安全、API 与完整 Python 实现。

---

全局视角：Webhook → 审核 → 回写（Mermaid）

sequenceDiagram
  participant GH as GitHub/GitLab
  participant GW as 公网入口\n(API Gateway)
  participant CS as CodeSentinel\nFastAPI
  participant AD as GitPlatformAdapter
  participant RP as ReviewPipeline\n(下一讲串联)
  participant API as 平台 REST API

  GH->>GW: POST /hooks/github
  GW->>CS: 转发原始 body + headers
  CS->>CS: 验签/令牌校验
  CS->>AD: parse_event(pr_meta)
  AD->>API: GET pull/files / diff
  API-->>AD: diff + refs
  AD->>RP: enqueue_review(job)
  RP-->>AD: ReviewReport
  AD->>API: POST review comments
  AD->>API: POST check/status
  API-->>GH: UI 展示评论/检查项

---

PR 审核生命周期：状态机（Mermaid）

stateDiagram-v2
  [*] --> idle
  idle --> pending: webhook 接收
  pending --> running: 任务开始
  running --> success: 无阻塞项
  running --> failure: 存在阻塞 finding
  running --> neutral: 仅提示/跳过
  success --> stale: PR 新提交
  failure --> stale: PR 新提交
  neutral --> stale: PR 新提交
  stale --> pending: 重新排队
  success --> [*]
  failure --> [*]
  neutral --> [*]

---

核心原理：事件、鉴权、API 与评论模型

1. Webhook 为什么是推送模型

轮询托管平台 API 会浪费配额、延迟高、且难以做到「几乎实时」。Webhook 让平台在事件发生时主动通知你。代价是：你必须处理重试、重复投递、乱序到达，以及公网暴露带来的攻击面。

2. GitHub 验签：HMAC-SHA256

GitHub 在请求头提供 X-Hub-Signature-256，值为 sha256=<hex>。你使用仓库配置的 secret 对原始 body 做 HMAC，比较常量时间相等。注意：必须用原始字节 body，不能在 JSON 解析后再序列化回字符串，否则签名不一致。

3. GitLab 验签：Token 与可选 JWT

GitLab Secret Token 通过 X-Gitlab-Token 传递，对比即可。部分企业实例还会叠加 IP 允许列表与反向代理校验。教学实现以 token 为主。

4. 事件类型与过滤

GitHub pull_request 的 opened、synchronize、reopened 通常需要触发审核；edited 是否触发取决于你是否关心标题描述。GitLab Merge Request Hook 类似。务必忽略无关事件，否则你会被平台限流。

5. 拉取 diff：GitHub pulls/{n}/files

文件级 patch 适合做行内评论定位。若你需要统一文本，可进一步拉取 application/vnd.github.diff。注意分页与超大 PR 的分片策略。

6. 行内评论：GitHub Pulls Review API

创建 review 时可以使用 comments 数组，包含 path、position 或 line（随 API 版本变化）。教学示例使用简化字段，并提示生产需对齐官方最新 schema。

7. 提交状态：Checks API vs Commit Statuses

GitHub 现代推荐 GitHub Checks，但 Commit Status API 更简单。教学实现使用 repos/{owner}/{repo}/statuses/{sha} 设置 pending/success/failure。

8. GitLab MR 讨论与 Pipeline 状态

GitLab 可在 MR 上创建 discussion，并把外部状态写进 commit status 或集成 Pipeline。适配器要统一成 CodeSentinel 内部 DTO：ReviewPost、StatusUpdate。

9. 幂等与去重

平台可能重复投递同一 delivery id 或同一 action。应用层要用 (repo, pr_number, head_sha) 做幂等键：同一 SHA 不重复全量审核，除非手动重跑。

10. 权限最小化

GitHub App 与 fine-grained PAT 的权限要最小化：通常需要 pull_requests: read/write（视评论需求）、statuses: write、metadata: read。不要把 org admin token 放进服务。

11. 速率限制与退避

遇到 403/429 要指数退避，并尊重 Retry-After。CodeSentinel 应把任务丢进队列而不是阻塞 webhook 线程。

12. 机密管理

WEBHOOK_SECRET、GITHUB_TOKEN 应来自密钥管理系统，不进仓库。日志必须脱敏。

13. 与异步任务系统的关系

Webhook 处理器应尽快返回 200，避免平台判定超时重试。重审核应异步化：本讲示例同步调用 pipeline 占位函数，生产换 worker。

14. 多租户

SaaS 化时需要按组织路由凭据：(installation_id) 或 (group_id) 映射 token。

15. 与下一讲管线的边界

本讲 run_review_stub 代表下一讲 ReviewPipeline。接口先定型，避免返工。

16. 评论噪音控制

把行内评论限制在最高优先级 findings；其余进摘要。否则大 PR 会刷爆页面。

17. 审核「请求更改」与「批准」

GitHub Review 事件包含 REQUEST_CHANGES/APPROVE。自动系统通常用 status failure 表达阻塞，而不用冒充人类批准。

18. 合规与数据驻留

diff 可能含个人信息与密钥。审核平台的数据保留策略要与法务对齐。

19. 私有化部署

GitHub Enterprise Server 与 GitLab self-managed 的 base URL 不同，适配器需配置 api_base。

20. 观测

对每次 webhook 记录 event_id、耗时、是否验签失败、以及写回评论是否成功，便于排障。

21. 伪造请求防护不止验签

还要校验事件来源 IP（弱）、使用 mTLS（强）、或在网关层做 WAF。验签是必要非充分条件。

22. 事件 schema 演进

平台会增加字段，解析应宽松：忽略未知字段，避免硬崩。

23. 与 CODEOWNERS 的关系

自动评论应 @ 相关 owner 仅在必要时，避免骚扰。

24. 与 Draft PR

Draft PR 是否审核：常见策略是仅跑轻量规则或跳过 LLM 调用。

25. 与 fork PR

fork PR 的密钥与权限模型更敏感：谨慎拉取/workflows，遵循组织安全策略。

26. 评论 Markdown 限制

平台对 Markdown 渲染与长度有限制，摘要应短。

27. 失败重试与死信

写评论失败要进入重试队列；超过次数进 DLQ 人工处理。

28. 与 Jira/ONES 联动

可在状态机 failure 时创建缺陷单（可选）。

29. 多环境

staging 与 prod 用不同 webhook secret 与不同 GitHub App。

30. 与模块二 review 聚合对齐

内部仍应创建 review_id 记录 findings，即使平台侧评论成功，也要保证内部审计追踪一致。

31. 交付节奏：先只读，后写回

生产落地建议分两阶段。第一阶段只接收 webhook、验签、拉 diff、写内部审计日志，但不在 PR 上发评论——这能验证事件过滤、凭据与网络连通性。第二阶段再打开写回，并把失败重试队列补齐。跳跃式上线最容易在「评论风暴」与「状态抖动」上翻车。

32. 评论 ID 与更新策略

GitHub 的 issue comment 与 review comment 更新策略不同。若你希望同一条摘要随 head sha 更新，通常做法是每次推送发新评论并在摘要顶部标注 head_sha，或删除旧评论（权限更高且复杂）。大多数团队选择「每次推送一条新摘要」但限制条数，并在最新摘要中链接历史。

33. 与 Checks 的上下文命名

Commit status 的 context 必须稳定，例如 codesentinel/review。若你频繁改名，分支保护规则会失效，研发会困惑「到底看哪一个检查项」。对多子系统，可用 codesentinel/security、codesentinel/quality 分层。

34. 与 PR 标签自动化

可以在审核开始时自动打 codesentinel:running，完成后再替换为 codesentinel:passed/failed。标签驱动工作流在大型组织很常见，但要避免与其他 bot 冲突。

35. 与私有仓库的凭据隔离

多租户平台中，不同组织使用不同 token 是硬要求。不要把所有仓库共用一颗超级 token：一旦泄露，攻击面覆盖整个公司。GitHub App 的安装级 token 通常是更优解。

36. 与「仅评论」和「请求更改」的策略选择

REQUEST_CHANGES 对团队心理影响更强，也可能影响合并权限策略。自动系统默认 COMMENT 更安全；只有当存在确定性高危 finding（例如密钥泄露）才考虑 REQUEST_CHANGES（仍建议由策略开关控制）。

37. 与 Git 大文件与生成代码

某些 PR 会包含生成代码或大体积迁移文件。webhook 处理应先做路径过滤与大小阈值：超过阈值的文件跳过详细规则，只给出提示，避免审核耗时失控。

38. 与「空提交」和 force push

synchronize 事件可能由 force push 触发，head sha 会变化。状态机必须以 head_sha 为版本锚点，否则会出现「评论贴在旧提交上」的错位体验。

39. 与并发：同一 PR 多个任务

如果研发快速连推两次，可能有两个 worker 同时运行。需要用分布式锁（Redis）锁住 (owner,repo,number)，或在队列里合并任务只保留最新 sha。

40. 与 SLA：审核超时的产品体验

长时间 pending 会让研发以为系统坏了。超时后应写回一条评论说明原因，并把状态置为 error，提示重试入口。

41. 与审计日志字段

建议记录：delivery_id、event_action、head_sha、installation_id（若用 GitHub App）、处理耗时、写回 API 状态码、以及内部 trace_id。这些字段能把一次「评论没出现」从猜测变成定位。

42. 与本地复现：fixture payloads

把真实 webhook payload 脱敏后存成 tests/fixtures/github_pr_opened.json，在单元测试里回放，比手工 curl 更稳定。

43. 与 OpenAPI：平台 API 版本漂移

GitHub X-GitHub-Api-Version 应固定团队正在使用的版本，并定期升级。升级前跑集成测试，尤其关注 review comments 字段。

44. 与 GitLab merge_request 事件差异

不同 GitLab 版本字段略有差异；解析要宽松，且要对缺失 last_commit.id 做保护，否则会把状态写到空 sha。

45. 与私有化网络

若 CodeSentinel 部署在内网，而 GitHub 在公网，通常由 GitHub 访问不到你。解决方案包括：使用 GitHub Enterprise、使用 GitHub App 的 webhook 代理、或使用可回拨的桥接服务。选型属于架构决策，要提前与信息安全部门对齐。

46. 与「只审核变更行」

行内评论应尽量落在 diff 的右侧行（RIGHT），并对删除侧（LEFT）评论谨慎处理。教学示例使用 side=RIGHT，生产需根据 patch 上下文计算合法行号。

47. 与国际化团队

评论语言策略要统一：中文团队用中文，跨国团队用英文，或双语。不要在同一仓库混用多种语言模板，除非按路径区分（例如 docs/zh/*）。

48. 与移动端通知

过密的评论会刷屏移动端。摘要优先、行内精选，是移动端友好策略。

49. 与「人工 override」入口

在 PR 评论模板里提供链接：如何申请 override、如何报告误报。把对抗成本降下来，平台才活得下去。

50. 与本模块叙事的关系

第 27~28 讲产出 findings 与质量分，本讲负责把它们送达工程师眼前；第 30 讲负责把各 stage 串成可靠系统。没有本讲，模块四只是离线工具；有了本讲，CodeSentinel 才进入协作闭环。

---

代码实战：FastAPI Webhook + GitHub 客户端 + 状态机

下面给出 git_integration_demo.py（单文件可运行，Python 3.10+）。依赖：fastapi, uvicorn, httpx。安装：

pip install fastapi uvicorn httpx

# git_integration_demo.py
from __future__ import annotations

import hashlib
import hmac
import json
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Literal

import httpx
from fastapi import FastAPI, Header, HTTPException, Request, Response

# ------------- Domain DTO -------------


@dataclass
class PullRequestRef:
    owner: str
    repo: str
    number: int
    head_sha: str
    base_sha: str
    html_url: str


@dataclass
class ReviewJob:
    job_id: str
    platform: Literal["github", "gitlab"]
    pr: PullRequestRef
    raw_event: dict[str, Any]


@dataclass
class ReviewFinding:
    path: str
    line: int | None
    severity: str
    message: str


@dataclass
class ReviewReport:
    summary: str
    findings: list[ReviewFinding] = field(default_factory=list)
    blocking: bool = False


# ------------- Review status machine -------------


class ReviewState(str, Enum):
    idle = "idle"
    pending = "pending"
    running = "running"
    success = "success"
    failure = "failure"
    neutral = "neutral"
    stale = "stale"


@dataclass
class ReviewStatusRecord:
    key: str
    state: ReviewState
    head_sha: str


class ReviewStatusManager:
    def __init__(self) -> None:
        self._records: dict[str, ReviewStatusRecord] = {}

    @staticmethod
    def make_key(owner: str, repo: str, number: int) -> str:
        return f"{owner}/{repo}#{number}"

    def on_webhook(self, pr: PullRequestRef) -> ReviewStatusRecord:
        key = self.make_key(pr.owner, pr.repo, pr.number)
        rec = self._records.get(key)
        if rec is None:
            rec = ReviewStatusRecord(key=key, state=ReviewState.idle, head_sha=pr.head_sha)
        if rec.head_sha != pr.head_sha and rec.state not in (ReviewState.idle,):
            rec.state = ReviewState.stale
        rec.head_sha = pr.head_sha
        rec.state = ReviewState.pending
        self._records[key] = rec
        return rec

    def mark(self, key: str, state: ReviewState) -> None:
        rec = self._records.get(key)
        if rec is None:
            return
        rec.state = state


# ------------- GitHub signature -------------


def verify_github_signature(secret: str, body: bytes, signature_header: str | None) -> None:
    if not signature_header or not signature_header.startswith("sha256="):
        raise HTTPException(status_code=401, detail="missing signature")
    mac = hmac.new(secret.encode("utf-8"), msg=body, digestmod=hashlib.sha256)
    expected = "sha256=" + mac.hexdigest()
    if not hmac.compare_digest(expected, signature_header):
        raise HTTPException(status_code=401, detail="bad signature")


def verify_gitlab_token(expected: str, token_header: str | None) -> None:
    if not token_header or not hmac.compare_digest(expected, token_header):
        raise HTTPException(status_code=401, detail="bad token")


# ------------- GitHub API client (httpx) -------------


class GitHubClient:
    def __init__(self, token: str, *, api_base: str = "https://api.github.com") -> None:
        self._client = httpx.Client(
            base_url=api_base.rstrip("/"),
            headers={
                "Authorization": f"Bearer {token}",
                "Accept": "application/vnd.github+json",
                "X-GitHub-Api-Version": "2022-11-28",
            },
            timeout=30.0,
        )

    def close(self) -> None:
        self._client.close()

    def get_pr_files(self, owner: str, repo: str, number: int) -> list[dict[str, Any]]:
        r = self._client.get(f"/repos/{owner}/{repo}/pulls/{number}/files")
        r.raise_for_status()
        return r.json()

    def create_issue_comment(self, owner: str, repo: str, number: int, body: str) -> None:
        r = self._client.post(f"/repos/{owner}/{repo}/issues/{number}/comments", json={"body": body})
        r.raise_for_status()

    def create_pull_request_review(
        self,
        owner: str,
        repo: str,
        number: int,
        *,
        commit_id: str,
        body: str,
        comments: list[dict[str, Any]],
        event: Literal["COMMENT", "REQUEST_CHANGES", "APPROVE"] = "COMMENT",
    ) -> None:
        payload = {"commit_id": commit_id, "body": body, "event": event, "comments": comments}
        r = self._client.post(f"/repos/{owner}/{repo}/pulls/{number}/reviews", json=payload)
        r.raise_for_status()

    def set_commit_status(
        self,
        owner: str,
        repo: str,
        sha: str,
        *,
        state: Literal["pending", "success", "failure", "error"],
        context: str,
        description: str,
        target_url: str | None = None,
    ) -> None:
        payload: dict[str, Any] = {
            "state": state,
            "description": description[:140],
            "context": context,
        }
        if target_url:
            payload["target_url"] = target_url
        r = self._client.post(f"/repos/{owner}/{repo}/statuses/{sha}", json=payload)
        r.raise_for_status()


# ------------- Event parsing -------------


def parse_github_pull_request(payload: dict[str, Any]) -> PullRequestRef | None:
    if payload.get("action") not in {"opened", "synchronize", "reopened"}:
        return None
    pr = payload.get("pull_request") or {}
    head = pr.get("head") or {}
    base = pr.get("base") or {}
    repo = pr.get("base", {}).get("repo", {}) or {}
    full_name = repo.get("full_name", "")
    if "/" not in full_name:
        return None
    owner, name = full_name.split("/", 1)
    return PullRequestRef(
        owner=owner,
        repo=name,
        number=int(pr["number"]),
        head_sha=str(head.get("sha", "")),
        base_sha=str(base.get("sha", "")),
        html_url=str(pr.get("html_url", "")),
    )


def parse_gitlab_merge_request(payload: dict[str, Any]) -> PullRequestRef | None:
    obj = payload.get("object_attributes") or {}
    if obj.get("action") not in {"open", "update"}:
        return None
    project = payload.get("project") or {}
    path = project.get("path_with_namespace", "")
    if "/" not in path:
        return None
    owner, name = path.split("/", 1)
    last_commit = obj.get("last_commit") or {}
    return PullRequestRef(
        owner=owner,
        repo=name,
        number=int(obj["iid"]),
        head_sha=str(last_commit.get("id", "")),
        base_sha=str(obj.get("target_branch", "")),
        html_url=str(obj.get("url", "")),
    )


# ------------- Stub pipeline -------------


def run_review_stub(job: ReviewJob) -> ReviewReport:
    # 下一讲替换为真实 ReviewPipeline
    findings = [
        ReviewFinding(
            path="README.md",
            line=1,
            severity="low",
            message="stub: 记得补充 CodeSentinel 接入说明",
        )
    ]
    return ReviewReport(
        summary="CodeSentinel：本构建为 Webhook 集成演示（stub pipeline）。",
        findings=findings,
        blocking=False,
    )


# ------------- FastAPI app -------------


def build_app(*, github_secret: str, github_token: str, gitlab_token: str) -> FastAPI:
    app = FastAPI(title="CodeSentinel Git Integration Demo", version="0.1.0")
    status_mgr = ReviewStatusManager()
    gh = GitHubClient(github_token)

    @app.on_event("shutdown")
    def _close() -> None:
        gh.close()

    @app.post("/hooks/github")
    async def github_hook(
        request: Request,
        response: Response,
        x_hub_signature_256: str | None = Header(default=None),
        x_github_delivery: str | None = Header(default=None),
    ) -> dict[str, Any]:
        body = await request.body()
        verify_github_signature(github_secret, body, x_hub_signature_256)
        payload = json.loads(body.decode("utf-8"))
        event = request.headers.get("X-GitHub-Event", "")
        if event != "pull_request":
            return {"ignored": True, "event": event}

        pr = parse_github_pull_request(payload)
        if pr is None:
            return {"ignored": True, "reason": "action_not_interesting"}

        rec = status_mgr.on_webhook(pr)
        status_mgr.mark(rec.key, ReviewState.running)

        gh.set_commit_status(
            pr.owner,
            pr.repo,
            pr.head_sha,
            state="pending",
            context="codesentinel/review",
            description="审核排队/运行中",
            target_url=pr.html_url,
        )

        job = ReviewJob(job_id=str(uuid.uuid4()), platform="github", pr=pr, raw_event=payload)
        report = run_review_stub(job)

        inline_comments: list[dict[str, Any]] = []
        for f in report.findings[:3]:
            if f.line is None:
                continue
            inline_comments.append(
                {
                    "path": f.path,
                    "side": "RIGHT",
                    "line": f.line,
                    "body": f"[{f.severity.upper()}] {f.message}",
                }
            )

        gh.create_pull_request_review(
            pr.owner,
            pr.repo,
            pr.number,
            commit_id=pr.head_sha,
            body=report.summary,
            comments=inline_comments,
            event="COMMENT",
        )

        final = "failure" if report.blocking else "success"
        gh.set_commit_status(
            pr.owner,
            pr.repo,
            pr.head_sha,
            state=final,
            context="codesentinel/review",
            description="审核完成" if final == "success" else "审核失败(阻塞项)",
            target_url=pr.html_url,
        )

        status_mgr.mark(rec.key, ReviewState.success if final == "success" else ReviewState.failure)
        return {"ok": True, "delivery": x_github_delivery, "job": job.job_id}

    @app.post("/hooks/gitlab")
    async def gitlab_hook(
        request: Request,
        x_gitlab_token: str | None = Header(default=None),
    ) -> dict[str, Any]:
        body = await request.body()
        verify_gitlab_token(gitlab_token, x_gitlab_token)
        payload = json.loads(body.decode("utf-8"))
        pr = parse_gitlab_merge_request(payload)
        if pr is None:
            return {"ignored": True}
        # 教学版：GitLab 写回略（避免双实现篇幅过长），仅返回解析结果
        return {"ok": True, "parsed": pr}

    return app


# 便于 uvicorn 字符串导入：export 默认 app 需环境变量
import os

app = build_app(
    github_secret=os.environ.get("GITHUB_WEBHOOK_SECRET", "devsecret"),
    github_token=os.environ.get("GITHUB_TOKEN", ""),
    gitlab_token=os.environ.get("GITLAB_WEBHOOK_TOKEN", "devgitlab"),
)

运行提示：真实调用 GitHub API 需要有效 GITHUB_TOKEN；本地联调可用 GITHUB_TOKEN 为空时注释掉写回逻辑，或改用 mock。生产务必使用队列异步化，不要把 httpx.Client 阻塞在 webhook 请求线程里长期持有。

---

GitLab 适配要点（补充说明，避免双实现淹没篇幅）

GitLab 创建 MR 评论可使用 POST /projects/:id/merge_requests/:iid/notes；更精细的行评论需要 discussions API 与 position 对象。GitPlatformAdapter 建议定义统一方法：fetch_changes()、post_summary()、post_inline()、set_status()。GitHub 与 GitLab 分别实现子类，在 webhook 层只做 adapter = factory(platform)。

---

生产环境实战：从演示到可运维系统

第一，快速返回：webhook 处理目标应在数百毫秒内返回 202/200；重任务交给 Celery/RQ/Arq。本讲同步实现只为教学可读。

第二，重试风暴：设置 idempotency_key 持久化，避免重复评论。可在摘要里带 head_sha 指纹。

第三，权限：GitHub 评论失败常见原因是 token 权限不足或 PR 来自 fork；需要按组织策略分支处理。

第四，大 PR 分片：先拉 files 列表，按路径过滤核心目录，避免全量扫描拖垮审核。

第五，机密扫描：在写回评论前扫描 findings 是否含密钥，避免二次泄露。

第六，审计：保存平台 delivery id 与内部 job_id 映射。

第七，多区域：GitHub 可能在不同区域延迟不同，超时要有分级。

第八，灰度：新规则先对 10% 仓库开启。

第九，回滚：一键关闭 webhook 或切换 dry-run 模式，只写内部不落评论。

第十，监控：验签失败次数突增通常是攻击或配置错误。

第十一，合规：根据数据分类，决定是否允许把 diff 发送到外部 LLM。

第十二，与 SSO：企业实例 token 轮换策略要提前设计。

第十三，与 merge queue：状态检查名称要与队列配置一致。

第十四，与 required reviews：自动评论不会替代人工审批，除非组织明确策略。

第十五，与 CODEOWNERS bot：避免多个 bot 互相触发循环 webhook（需要事件过滤）。

第十六，与 monorepo：路径过滤基于 changed files。

第十七，与 submodule：diff 可能不完整，需要提示风险。

第十八，与 LFS：文本 diff 可能异常，审核应跳过二进制。

第十九，与机器人账号：建议使用专用 GitHub App，而不是个人账号 PAT。

第二十，与本地开发：用 smee.io 或 ngrok 暴露 webhook，配合测试仓库。

第二十一，与依赖升级：FastAPI/Starlette 升级可能改变请求体缓存行为；升级后必须回归验签用例。

第二十二，与时间同步：极少数签名方案依赖时间窗；服务器 NTP 漂移会导致神秘失败。

第二十三，与内容编码：确保 body 以字节方式读取；编码处理错误会破坏签名与 JSON。

第二十四，与负载均衡：多层代理可能剥离关键头；网关需透传 X-Hub-Signature-256。

第二十五，与双活部署：两个实例同时处理同一 delivery 可能导致重复写回；需要分布式锁或主备消费。

第二十六，与成本：GitHub API 调用计费虽不像云资源那样直观，但限流成本是研发等待；缓存 files 结果能省配额。

第二十七，与可观测性：把 x-github-delivery 打进 trace，能在 APM 上拼出完整链路。

第二十八，与错误页面：当审核失败，评论里给出「平台管理员联系方式」比只抛栈更专业。

第二十九，与多规则并发：未来你可能并行跑 security/perf/quality；状态检查可用多个 context 表示子结果。

第三十，与合规模块：某些行业要求保留审计记录 7 年；webhook payload 存储策略要提前设计。

---

Webhook 入口安全分层（Mermaid）

flowchart TB
  Internet["公网流量"] --> WAF["WAF / 速率限制"]
  WAF --> GW["API Gateway\nmTLS 可选"]
  GW --> APP["FastAPI\n验签"]
  APP --> Q["任务队列"]
  Q --> W["Worker\n拉 diff + 审核"]
  W --> API["GitHub/GitLab API\n写评论/状态"]

---

本讲小结（Mermaid Mindmap）

mindmap
  root((第29讲\nGit 集成))
    安全
      GitHub HMAC
      GitLab Token
      机密管理
    能力
      拉取 diff
      行内评论
      commit status
    工程
      Adapter 隔离差异
      状态机幂等
      异步队列(生产)
    交付
      FastAPI webhook
      GitHubClient httpx

---

延展：GitLab 写回最小示例（补充完整度）

下面片段演示 GitLab 使用 python-gitlab 或 httpx 写一条 MR note（教学伪代码，占位 URL）。在真实环境你需要 GITLAB_TOKEN 具备 api 权限，并把 project_id 与 mr_iid 从 webhook payload 正确映射。

import httpx

def post_gitlab_mr_note(*, base_url: str, token: str, project_id: int, mr_iid: int, body: str) -> None:
    url = f"{base_url.rstrip('/')}/api/v4/projects/{project_id}/merge_requests/{mr_iid}/notes"
    headers = {"PRIVATE-TOKEN": token}
    r = httpx.post(url, headers=headers, json={"body": body}, timeout=30.0)
    r.raise_for_status()

行内评论需要 POST /projects/:id/merge_requests/:iid/discussions，并提供 position（base_sha、head_sha、start_sha、new_path、new_line 等）。CodeSentinel 的 GitPlatformAdapter.gitlab 实现应把 unified diff 解析为 hunk，再映射到 new_line。不要手工猜行号：必须以平台返回的 diff 为准。

与 codesentinel-clean-lab 的对接建议

当你希望在内部 review 聚合里保留一份「平台无关」记录，推荐流程是：webhook 到达后先 POST /reviews 创建审核，再 POST /reviews/{id}/start，审核过程中把 findings 写入 POST /reviews/{id}/findings，最后 POST /reviews/{id}/complete（具体路径以实验仓库 API 为准）。平台评论可以只放摘要，详细 findings 以内部链接跳转，这样即使 GitHub 评论被折叠，审计仍完整。

平台字段映射表（心智模型）

• GitHub：pull_request.number 是 PR 编号；head.sha 是审核锚点。
• GitLab：object_attributes.iid 是 MR IID（注意不是全局 ID）；project.id 是数字项目 ID，常用于 API。
• 评论定位：GitHub 偏向 pull review comments；GitLab 偏向 discussions + position。
• 状态：GitHub commit status 简单；GitLab 可用 external status（视版本与配置）。

把这张表写进团队内部集成手册，可以减少「同一个概念换平台就迷路」的沟通成本。

思考题

1. 为什么 webhook 验签必须使用原始 body？如果你先 await request.json() 再 json.dumps，会遇到什么诡异问题？

2. 同一 PR 短时间内多次推送，状态机如何避免旧任务覆盖新任务结果？你需要哪些字段作为版本控制？

3. GitHub Checks 与 Commit Statuses 各适合什么组织场景？你会如何在 CodeSentinel 中渐进演进？

4. 你会如何把「重复 delivery」与「正常重试」区分开，并在日志里一眼识别？

---

下一讲预告

下一讲是模块四综合实战：我们把 webhook、diff 解析、安全审核、架构合规、性能检测、质量评分与 AGENTS.md 合规串联成 ReviewPipeline，输出统一 ReviewReport，用 Markdown 模板回写 PR，并提供 Docker Compose 与 curl 模拟完整周期。

补充阅读建议：把 GitHub 官方文档中「Securing your webhooks」与「REST API：Pulls」两章作为手边参考；把 GitLab 的「Webhooks」和「Merge requests API」加入书签。你会频繁回到这些页面核对字段名与示例 JSON。对于安全团队，准备一页「CodeSentinel 数据流图」说明哪些数据出站、哪些数据留存、哪些数据进入模型推理，这能显著加速安全评估审批。

---

术语表（本讲高频）

• Delivery：平台对单次 webhook 投递的唯一标识，用于排障与去重。
• Head SHA：PR 最新提交的提交哈希，是状态检查与评论定位的关键锚点。
• Idempotency：同一事件重复到达时系统仍保持一致，不产生重复副作用。
• Adapter：把不同平台 API 映射到统一内部 DTO 的隔离层。
• Status context：状态检查的名称空间键，用于分支保护规则绑定。

---

常见踩坑清单（上线前自检）

1. 验签使用了反序列化后的 JSON 文本，导致随机性空格差异让签名永远失败。
2. 在异步路由里使用同步 httpx.Client 高并发阻塞事件循环；应改用 AsyncClient 或线程池隔离。
3. 对 fork PR 使用过高权限 token，造成潜在越权风险。
4. 评论定位行号用了本地 workspace 行号，而不是 diff 的 new line。
5. 未处理 API 分页，导致只审核了前 30 个变更文件。

把清单贴在运维手册首页，能节省大量排障时间。务必收藏。

---

与产品角色的沟通话术（可选）

当产品问「这玩意儿对交付速度有什么帮助」，你可以回答：我们把高概率事故（密钥泄露、性能坑、规范违背）前移到 PR 阶段，减少返工与夜间应急，从而缩短从开发到稳定上线的时间。自动评论不是增加摩擦，而是把隐性成本显性化。若产品担心评论噪音，强调摘要 + 分级的策略，以及 dry-run 与渐进启用。

---

与测试策略的衔接

集成测试应覆盖：验签失败、事件忽略、API 403/429、空 diff、超大 diff、以及重复 delivery。对于写回 API，建议使用录播（VCR）或 httpx mock transport，不要把真实 token 写进 CI。对状态机做单测：同一 key 在不同 head sha 下应从 stale 进入 pending。

---

与「平台中立」相关的长期演进

当组织同时存在 GitHub 与 GitLab，CodeSentinel 不应复制两套业务逻辑。正确做法是：webhook 层解析出统一 ChangeSet（仓库、变更文件、patch 文本、元信息），审核核心只消费 ChangeSet。这会让第 30 讲的 ReviewPipeline 更干净，也会让未来接入其他平台成本可控。