企业官网建设流程全解析

Archon GitHub 适配器接入指南：用 Webhook 打通 Issue 与 Pull Request 的 AI 协作

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

本指南面向 Archon 使用者与运维人员，完整讲解如何将 Archon 通过 GitHub Webhook 接入你的仓库，使团队成员可以在 Issue 或 Pull Request 的评论中通过@mention直接调用 AI 编码助手，实现"评论即指令"的协作闭环。读完本文，你将掌握：Webhook 密钥与公网隧道的配置、GitHub Webhook 的事件订阅、GITHUB_TOKEN/WEBHOOK_SECRET等环境变量的完整含义，以及多仓库扩展、安全加固与源码级实现原理。

概览：为什么用 Webhook 连接 GitHub

Archon 的 GitHub 适配器（packages/adapters/src/forge/github/adapter.ts）实现了一条完全事件驱动的通道：GitHub 将 Issue 评论、PR 评论、Check Run 完成等事件推送到 Archon 的/webhooks/github端点，适配器验签后解析事件，识别出针对机器人的@mention，进而自动克隆仓库、加载项目命令、注入 Issue/PR 上下文，并把 AI 的回复以完整评论的形式写回对应线程。

这一模式带来几个典型收益：

• 评审自动化：在 PR 评论中让机器人分析实现、审查 diff、给出修改建议；
• Bug 跟进：在 Issue 评论中让机器人复现、定位并分析缺陷；
• 上下文连续：同一 Issue/PR 下的多次提及共享同一会话，AI 能记住之前的讨论；
• 低摩擦协作：团队成员无需接触 Archon 的 Web 界面，在 GitHub 上即可完成交互。

两种认证模式的取舍

官方文档 github.md 说明的是PAT 模式（Personal Access Token），即使用一个共享的GITHUB_TOKEN代表机器人发言；而仓库还提供了推荐的 GitHub App 模式。两者对比如下：

文档明确建议：共享同一台 Archon 实例的团队优先使用 GitHub App 模式。PAT 模式作为 legacy 路径仍然可用，适合 solo 安装。此外，服务端启动逻辑（packages/server/src/index.ts）会强制要求二选一：同时配置两套变量会导致启动失败，因此配置前需先确定模式。

前置条件

在开始配置前，请确认以下内容：

• Archon 服务端已运行（快速上手见 Getting Started 总览）；
• 目标 GitHub 仓库已启用 Issues 功能；
• 环境中已设置GITHUB_TOKEN；
• 本地开发时需要一个公网可达的 Webhook 接收端点（下文 ngrok / Cloudflare Tunnel 小节介绍）。

第一步：生成 Webhook 密钥

Webhook 密钥（Secret）用于 GitHub 与 Archon 之间的消息签名校验，两端必须完全一致。生成方式：

Linux / macOS：

openssl rand -hex 32

Windows PowerShell：

-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

保存生成的 64 位十六进制字符串，第三步（GitHub 配置）与第四步（环境变量）都会用到它。

第二步：暴露本地服务（仅开发环境）

GitHub 的 Webhook 只能投递到公网 HTTPS 地址，本地开发时需要用隧道将 Archon 的 3090 端口暴露出去。

方案 A：ngrok（免费版）

# 安装：https://ngrok.com/download # 或 Windows: choco install ngrok # 或 macOS: brew install ngrok # 启动隧道 ngrok http 3090 # 复制输出的 HTTPS 地址（例如 https://abc123.ngrok-free.app） # 注意：免费版地址在重启后会变化

测试期间请保持该终端持续运行。

方案 B：Cloudflare Tunnel（持久地址）

# 安装：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/ cloudflared tunnel --url http://localhost:3090 # 从 Cloudflare Dashboard 获取持久地址

持久地址在服务重启后依然有效，适合频繁重启的开发场景。

生产部署：直接使用已部署的服务器域名（如https://your-domain.com），无需隧道。

第三步：在 GitHub 仓库配置 Webhook

进入仓库设置页：

• 导航到：https://github.com/owner/repo/settings/hooks
• 点击Add webhook
• 注意：若需接入多个仓库，必须为每个仓库分别添加 Webhook

Webhook 配置参数：

点击Add webhook后，确认投递记录显示绿色对勾（成功）。端点路径/webhooks/github由服务端在 packages/server/src/routes/webhooks.ts 中注册，它读取x-github-event、x-github-delivery与x-hub-signature-256请求头，再以原始请求体（c.req.text()）交给适配器的handleWebhook做签名校验——这是保证安全的关键实现细节：签名必须基于原始请求体计算，不能使用解析后的 JSON。

第四步：设置环境变量

在 Archon 的.env中配置：

WEBHOOK_SECRET=your_secret_from_step_1

重要：WEBHOOK_SECRET必须与第三步在 GitHub Webhook 配置中填入的值完全一致，否则所有投递都会因签名校验失败而被拒绝。服务端启动时若检测到GITHUB_TOKEN与WEBHOOK_SECRET未同时存在，会抛出 "GitHub PAT mode misconfigured" 错误（packages/server/src/index.ts）。

除这两个核心变量外，仓库还支持以下相关配置（见 configuration 参考文档）：

GITHUB_ALLOWED_USERS的解析逻辑位于 packages/adapters/src/forge/github/auth.ts：未配置或为空时进入开放访问模式（任何人可触发），配置后按逗号切分、去空白、转小写并做大小写不敏感匹配；被白名单拒绝的发送者会被静默忽略（只记录日志，不返回错误响应）。

第五步：输出模式说明

GitHub 适配器将getStreamingMode()硬编码为'batch'（packages/adapters/src/forge/github/adapter.ts）。原因在于 GitHub Issue 与 PR 最适合以单条完整评论呈现结果，而不是流式增量更新——流式输出会在评论区产生大量碎片化消息，造成刷屏。因此该适配器无需也无法配置 streaming 模式。

使用方式：通过 @mention 触发

在 Issue 或 PR 的评论中提及机器人即可交互，例如：

@archon can you analyze this bug? @archon prime the codebase @archon review this implementation

其中archon是默认的 @mention 名称，可通过GITHUB_BOT_MENTION（或回退链BOT_DISPLAY_NAME→ 配置的 botName）自定义，见 packages/server/src/index.ts。

首次提及的行为

• 自动将仓库克隆到~/.archon/workspaces/（对应源码中的ensureProjectStructure+cloneRepository流程，adapter.ts）；
• 若仓库中存在.archon/commands/（或配置的搜索路径），自动检测并加载其中的 Markdown 命令（autoDetectAndLoadCommands，adapter.ts）；
• 为 AI 注入完整的 Issue/PR 上下文：Issue 上下文包含编号、标题、作者、标签、状态与描述（buildIssueContext）；PR 上下文额外包含变更文件数、增删行统计，并提示可用gh pr diff <number>查看详细改动（buildPRContext，adapter.ts）。

后续提及的行为

• 恢复既有会话（conversationId 按owner/repo#number稳定构造）；
• 跨评论维持完整上下文：适配器会拉取最近 20 条评论（fetchCommentHistory，per_page=20）作为线程上下文，按时间正序拼接后随消息一并交给编排器（adapter.ts）。

重要行为边界

:::note只有评论会触发机器人。Issue/PR描述中的 @mention 会被忽略——描述里往往包含示例命令或使用说明，不应被当作机器人调用。对应实现中parseEvent明确不处理issues.opened与pull_request.opened事件（adapter.ts）。 :::

此外，适配器有两道自我触发防护：机器人发布评论时会在末尾附加隐藏标记<!-- archon-bot-response -->，收到含该标记的评论直接忽略；同时也会过滤评论作者为机器人自身登录名（App 模式下为<slug>[bot]）的评论（adapter.ts）。

添加更多仓库

服务运行后，只需为新仓库创建使用相同密钥的 Webhook 即可扩展。

方式一：GitHub UI

Repo Settings > Webhooks > Add webhook：

• Payload URL：你的服务器地址 +/webhooks/github
• Content type：application/json
• Secret：与.env中的WEBHOOK_SECRET相同
• Events：Check runs、Issues、Issue comments、Pull requests

方式二：CLI（gh）

# 读取现有 webhook 密钥 WEBHOOK_SECRET=$(grep WEBHOOK_SECRET .env | cut -d= -f2) # 为新仓库添加 webhook（替换 OWNER/REPO） gh api repos/OWNER/REPO/hooks --method POST \ -f "config[url]=https://YOUR_DOMAIN/webhooks/github" \ -f "config[content_type]=json" \ -f "config[secret]=$WEBHOOK_SECRET" \ -f "events[]=check_run" \ -f "events[]=issues" \ -f "events[]=issue_comment" \ -f "events[]=pull_request"

重要：所有仓库的 webhook 密钥必须完全一致。

Check Run 事件的作用

check_run投递用于快速唤醒 CI 等待：当工作流等待的 CI 检查完成时，适配器通过handleCompletedCheckRun匹配对应的checks.complete等待信号并调用signalWorkflowWait立即放行（adapter.ts）。它不是正确性必需项：即使 GitHub 未投递该事件，工作流也会在等待超时后自行再次探测 CI 状态。

源码视角：一次完整交互的调用链

从收到 Webhook 到回复落地的完整链路如下（核心实现在 adapter.ts 的handleWebhook）：

1. 验签：用WEBHOOK_SECRET对原始请求体计算 HMAC-SHA256，通过timingSafeEqual常量时间比较（verifySignature）；
2. 解析事件：check_run事件走 CI 唤醒分支；其余事件解析出 owner / repo / number / 评论内容；
3. 白名单校验：isGitHubUserAuthorized检查发送者是否在GITHUB_ALLOWED_USERS白名单内；
4. 关闭事件清理：Issue/PR 关闭（含合并）时触发cleanupWorktree，清理对应隔离工作树；
5. 自我触发过滤 + @mention 检测：含隐藏标记或机器人自身评论直接忽略；hasMention用正则@botMention[\s,:;]匹配（大小写不敏感，adapter.ts）；
6. 去重：DeliveryDeduplicator以comment:id:updated_at为键进行幂等去重，防止双重订阅或重投递导致重复处理；
7. 会话与代码库绑定：按owner/repo#number获取或创建会话，将会话关联到 codebase（自动克隆/同步仓库）；
8. 构造消息：剥离 @mention 前缀，按需注入 Issue/PR 富上下文；以/开头的斜杠命令会被确定性处理（仅取首行，附上gh issue view/gh pr view参考提示）；
9. 持锁派发：通过ConversationLockManager获取会话锁后调用handleMessage派发给编排器，回复经sendMessage写回 GitHub——超过 65,000 字符（GitHub 评论上限）的消息会按段落拆分后逐条发布（adapter.ts）。

整个端点接收层在 packages/server/src/routes/webhooks.ts：check_run事件采用同步失败确认（确保 GitHub 能重投递），其他事件异步处理并记录错误日志。适配器的单元与集成测试覆盖了上述大部分行为，例如 adapter.test.ts 与 workflow-signal.integration.test.ts。

生产部署建议

• 密钥管理：WEBHOOK_SECRET与GITHUB_TOKEN通过环境变量或密钥管理服务注入，勿提交到版本库；
• HTTPS 强制：生产环境务必启用 SSL 校验；隧道地址频繁变化不适合长期使用，请使用持久域名；
• 权限最小化：团队场景优先迁移到 GitHub App 模式，获得<slug>[bot]署名与 1 小时令牌轮换；如需按用户身份发言，可结合TOKEN_ENCRYPTION_KEY启用按用户 GitHub 身份路由（服务端 index.ts 中通过getUserToken注入实现）；
• 访问控制：对外暴露的实例建议配置GITHUB_ALLOWED_USERS白名单，防止无关用户触发 AI 调用；
• 多仓库扩展：统一使用同一WEBHOOK_SECRET，通过 docker-compose.yml / docker-compose.override.example.yml 等部署配置保持一致。

进一步阅读

• GitHub App 模式配置指南：团队共享实例的推荐方案，含细粒度权限表与事件订阅清单；
• configuration 参考文档：全部环境变量的完整说明；
• Getting Started 总览：Archon 服务端启动与基础配置。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon