尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

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

Archon GitHub 适配器接入指南:用 Webhook 打通 Issue 与 Pull Request 的 AI 协作 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 连接 GitHubArchon 的 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 模式。两者对比如下维度PAT 模式本指南GitHub App 模式适用场景单人单仓库的 solo 安装多成员共享一台 Archon 实例、多组织仓库评论署名全部以 PAT 所属账号头像发布slug[bot]的独立机器人身份Token 生命周期长期有效不会自动轮换安装令牌约 1 小时自动轮换Webhook每个仓库单独配置一个 App 对应一个 Webhook URL覆盖所有安装多组织支持受限支持按 (owner, repo) 自动路由到对应安装文档明确建议共享同一台 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 / macOSopenssl rand -hex 32Windows PowerShell-join ((1..32) | ForEach-Object { {0:x2} -f (Get-Random -Maximum 256) })保存生成的 64 位十六进制字符串第三步GitHub 配置与第四步环境变量都会用到它。第二步暴露本地服务仅开发环境GitHub 的 Webhook 只能投递到公网 HTTPS 地址本地开发时需要用隧道将 Archon 的 3090 端口暴露出去。方案 Angrok免费版# 安装https://ngrok.com/download # 或 Windows: choco install ngrok # 或 macOS: brew install ngrok # 启动隧道 ngrok http 3090 # 复制输出的 HTTPS 地址例如 https://abc123.ngrok-free.app # 注意免费版地址在重启后会变化测试期间请保持该终端持续运行。方案 BCloudflare 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注意若需接入多个仓库必须为每个仓库分别添加 WebhookWebhook 配置参数字段值Payload URL本地https://abc123.ngrok-free.app/webhooks/github生产https://your-domain.com/webhooks/githubContent typeapplication/jsonSecret粘贴第一步生成的密钥SSL verification建议启用Events选择 Let me select individual events勾选- Check runs- Issues- Issue comments- Pull requests点击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_SECRETyour_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逗号分隔的 GitHub 用户名白名单大小写不敏感空值表示开放访问开放访问GITHUB_BOT_MENTION机器人在 Issue/PR 中响应的 mention 名称回退到BOT_DISPLAY_NAMEGITHUB_ALLOWED_USERS的解析逻辑位于 packages/adapters/src/forge/github/auth.ts未配置或为空时进入开放访问模式任何人可触发配置后按逗号切分、去空白、转小写并做大小写不敏感匹配被白名单拒绝的发送者会被静默忽略只记录日志不返回错误响应。第五步输出模式说明GitHub 适配器将getStreamingMode()硬编码为batchpackages/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/对应源码中的ensureProjectStructurecloneRepository流程adapter.ts若仓库中存在.archon/commands/或配置的搜索路径自动检测并加载其中的 Markdown 命令autoDetectAndLoadCommandsadapter.ts为 AI 注入完整的 Issue/PR 上下文Issue 上下文包含编号、标题、作者、标签、状态与描述buildIssueContextPR 上下文额外包含变更文件数、增删行统计并提示可用gh pr diff number查看详细改动buildPRContextadapter.ts。后续提及的行为恢复既有会话conversationId 按owner/repo#number稳定构造跨评论维持完整上下文适配器会拉取最近 20 条评论fetchCommentHistoryper_page20作为线程上下文按时间正序拼接后随消息一并交给编排器adapter.ts。重要行为边界:::note只有评论会触发机器人。Issue/PR描述中的 mention 会被忽略——描述里往往包含示例命令或使用说明不应被当作机器人调用。对应实现中parseEvent明确不处理issues.opened与pull_request.opened事件adapter.ts。 :::此外适配器有两道自我触发防护机器人发布评论时会在末尾附加隐藏标记!-- archon-bot-response --收到含该标记的评论直接忽略同时也会过滤评论作者为机器人自身登录名App 模式下为slug[bot]的评论adapter.ts。添加更多仓库服务运行后只需为新仓库创建使用相同密钥的 Webhook 即可扩展。方式一GitHub UIRepo Settings Webhooks Add webhookPayload URL你的服务器地址 /webhooks/githubContent typeapplication/jsonSecret与.env中的WEBHOOK_SECRET相同EventsCheck runs、Issues、Issue comments、Pull requests方式二CLIgh# 读取现有 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验签用WEBHOOK_SECRET对原始请求体计算 HMAC-SHA256通过timingSafeEqual常量时间比较verifySignature解析事件check_run事件走 CI 唤醒分支其余事件解析出 owner / repo / number / 评论内容白名单校验isGitHubUserAuthorized检查发送者是否在GITHUB_ALLOWED_USERS白名单内关闭事件清理Issue/PR 关闭含合并时触发cleanupWorktree清理对应隔离工作树自我触发过滤 mention 检测含隐藏标记或机器人自身评论直接忽略hasMention用正则botMention[\s,:;]匹配大小写不敏感adapter.ts去重DeliveryDeduplicator以comment:id:updated_at为键进行幂等去重防止双重订阅或重投递导致重复处理会话与代码库绑定按owner/repo#number获取或创建会话将会话关联到 codebase自动克隆/同步仓库构造消息剥离 mention 前缀按需注入 Issue/PR 富上下文以/开头的斜杠命令会被确定性处理仅取首行附上gh issue view/gh pr view参考提示持锁派发通过ConversationLockManager获取会话锁后调用handleMessage派发给编排器回复经sendMessage写回 GitHub——超过 65,000 字符GitHub 评论上限的消息会按段落拆分后逐条发布adapter.ts。整个端点接收层在 packages/server/src/routes/webhooks.tscheck_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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表