自建 Multica 怎么创建 GitHub App 并连接让 PR 自动关联 issue【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica在 Multica Cloud 上GitHub 集成由官方 App 直接提供而自建self-host的 Multica 必须先在 GitHub 上创建自己的 GitHub App再配置环境变量、完成连接之后 Multica 才能根据 issue 标识自动关联 Pull Request并在 issue 详情页展示 PR 状态、CI 结果和合并冲突。整个集成是只读的它只读取安装时授权的仓库从不推送提交、评论或状态检查。本文对应 GitHub integration 文档 的 Self-hosting setup 一节适用于已按 Self-host quickstart 用 Docker Compose 跑起 Multica 的部署。开始前的准备Multica 服务已经启动并可登录工作区里已有 issue连接操作需要workspace owner 或 admin身份普通成员只能查看连接状态。GitHub 能通过 HTTPS 访问你的 API 主机。App 的 Setup URL 和 Webhook URL 都指向 API 地址下文记作api-host替换为你的 API 域名例如api.example.com。如果还是localhost:8080GitHub 无法回调需要先按 quickstart 配置反向代理和公网域名。明确一个长期保存的随机字符串作为 Webhook secret。注意这是Webhook secret不是 App 的 OAuth Client secret两边不一致时 GitHub 投递会返回401 invalid signature。第 1 步在 GitHub 创建 App在 GitHub 的Developer settings → GitHub Apps中创建 App按下表填写FieldValueHomepage URL你的 Multica 前端地址例如https://multica.example.comCallback URL留空Setup URLhttps://api-host/api/github/setup并启用Redirect on updateWebhook URLhttps://api-host/api/webhooks/githubWebhook secret你长期保存的那个随机字符串仓库权限Repository permissionsPermissionLevelMetadataRead-onlyContentsRead-onlyPR snapshot 查询需要它会读取 head commit 以及 mergeability 和 CI 汇总Pull requestsRead-onlyChecksRead-only用于展示 CI 状态Commit statusesRead-only用于聚合 legacy-status CI事件订阅Subscribe to eventsPull requestCheck suite、Check run、Status用于触发 CI 和 mergeability 刷新。如果你不需要在 Multica 里显示 CI可以跳过 Checks 和 Commit statuses 这两项权限及对应事件。但Contents 不能省——没有它 snapshot 查询会直接失败PR 卡片上的 merge 状态也会丢失。创建完成后记下三样东西App 的slugApp 公开 URL 的尾部例如https://github.com/apps/multica-acme的 slug 是multica-acme、App 设置页上的数字 App ID以及在Private keys → Generate a private key生成的PEM 私钥。第 2 步配置环境变量在 Multica 的.env中追加对照 Environment variables 文档 和仓库自带的 .env.exampleGITHUB_APP_SLUGmultica-acme GITHUB_WEBHOOK_SECRET第 1 步填入 App 的那个 webhook secret FRONTEND_ORIGINhttps://multica.example.com其中GITHUB_APP_SLUG和GITHUB_WEBHOOK_SECRET是最低要求两者任一缺失Connect GitHub 按钮会保持禁用webhook 端点也会拒绝处理事件。FRONTEND_ORIGIN是自建部署的必选项这里填用户访问的前端 origin。如果还希望 PR 卡片显示 CI 状态和 mergeability再补两个变量——Multica 用它们以 App 身份认证并拉取 GitHub API 快照GITHUB_APP_IDApp 设置页上的数字 App ID GITHUB_APP_PRIVATE_KEY完整 PEM 私钥保留 BEGIN/END 行与换行.env.example中对私钥格式有专门说明.env里多行 PEM 必须用双引号包住并保留真实换行未加引号的多行值会在第一行处截断GITHUB_APP_PRIVATE_KEY-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----GITHUB_APP_ID和私钥是可选的不配置时集成的其余功能正常PR 照常镜像、issue 照常自动关联并在合并后流转 Done只是 PR 卡片不显示 CI 和 merge 状态。第 3 步应用配置并重启服务修改.env后环境变量要等进程重启才会被重新读取而docker compose restart只重启容器、不会重新读取.env必须用up -d重建容器会短暂重建容器并中断服务连接数据在 volume 中不受影响docker compose -f docker-compose.selfhost.yml up -d如果你是升级已有部署按 GitHub integration 文档的说明先运行常规数据库迁移再重启 API 服务make migrate-up迁移是 forward-only 的升级前建议先备份数据库quickstart 给出了pg_dump的具体命令。使用 Docker Compose 自托管时backend 容器每次启动也会先跑迁移再对外服务用下面的命令确认迁移已完成curl -fsS http://localhost:8080/readyz预期响应为{status:ok,checks:{db:ok,migrations:ok}}。只要两个 check 不是ok说明新版本没有完成迁移先看 backend 日志再对外提供服务。第 4 步在 Multica 里完成连接打开Settings → GitHub。打开 GitHub integration 主开关。点击Connect GitHub会跳转到 GitHub。在 GitHub 上选择账户或组织授权全部仓库或自选一部分仓库。安装完成后回到 Multica连接状态显示在同一页面。页面上的四个开关各司其职GitHub integration是主开关关闭时下面三项停摆但 App 保持已连接PR sidebar控制 issue 详情里是否展示已关联 PRCo-authored-by会给 agent 生成的 commit 追加Co-authored-by: multica-agent githubmultica.aiAuto-link PRs负责从 PR 的分支名、标题和正文中识别 issue 标识。注意区分两个容易混淆的设置GitHub connection决定 Multica 从哪些仓库接收 PR 事件code repositories设置决定 agent 启动运行时可选哪些仓库。两者用途不同、分别配置。第 5 步用 issue 标识写 PR验证自动关联关联规则由Auto-link PRs开关驱动匹配时忽略大小写且只匹配当前工作区的 issue 前缀。一个 PR 可以关联多个 issue。最简单的写法是把 issue 标识放进分支名或 PR 标题。以 issueMUL-123为例替换为你自己的 issue 标识mul-123-fix-login-redirectMUL-123 Fix the redirect after login如果标识只出现在 PR 正文里必须使用 GitHub 的 close intent 句式Closes MUL-123 Fixes MUL-123 Resolves MUL-123正文中的普通提及例如Related to MUL-123不会被当作有效关联commit message 和 PR 评论也不触发关联。验证方式提交 PR 后打开对应 issue 的详情页Pull requests区块里应出现该 PR条目包含仓库、编号、标题、作者Open/Draft/Merged/Closed状态增删行数和变更文件数CI 状态全部通过附数量、部分失败列出失败项、部分进行中没配置 checks 的 PR 不显示此项——“没有 checks”从不被当作通过以及 mergeabilitymergeable/conflicting/blocked/behind。点击条目可打开 GitHub 上的 PR。CI 和 mergeability 来自 Multica 从 GitHub API 拉取的快照两者相互独立已合并或关闭的 PR 不再显示GitHub 暂时不可用时卡片保留上次快照并标记为 stale而不是变空白。合并后的流转规则同样值得核对Multica 只在全部满足下列条件时把 issue 移到Done至少一个已合并的关联 PR 使用了 close intent 且标识紧跟其后例如Closes MUL-123中间夹了其他词的写法如Closes login MUL-123不算该 issue 没有其他仍处于Open或Draft的有效关联 PR正文中的普通提及不算issue 当前不是done或cancelled。所以只在分支名或标题里写MUL-123只建立关联、不触发完成PR 未合并就被关闭也不完成 issue。状态变更会作为系统动作写入时间线并通知订阅了该 issue 的成员。常见排查项文档列出的排查对照现象检查Connect 按钮禁用GITHUB_APP_SLUG和GITHUB_WEBHOOK_SECRET是否真的到达了 API 进程Webhook 返回 401GitHub App 与 API 使用同一个 webhook secret然后从 GitHub 的Recent Deliveries重新投递PR 未关联仓库是否在 App 的授权范围内、Auto-link PRs 是否打开、标识是否属于当前工作区标识在正文里但不显示改用Closes MUL-123或把标识放进分支名或 PR 标题PR 卡片没有 CI 状态确认配置了GITHUB_APP_ID和GITHUB_APP_PRIVATE_KEYApp 具备只读的 Contents、Checks、Commit statuses 权限并订阅了对应事件没有 Contents 整个快照都会失败。给已安装的 App 加权限后各 installation 的所有者还必须在 GitHub 上批准后才生效PR 合并后 issue 没变成 Done确认 PR 用了 close intent并检查是否有其他关联 PR 仍为 Open 或 Draft边界与断开同一套 GitHub App 安装可以连接多个 Multica 工作区GitHub 事件分别流入各工作区并与各自工作区的 issue 前缀匹配工作区之间互不可见对方的 issue。在Settings → GitHub点Disconnect只解除当前工作区与这次安装的关系不会替你从 GitHub 卸载 App已有 PR 记录保留新事件停止流入该工作区。要在 GitHub 侧收回仓库授权需要从个人或组织的 GitHub App installations 页卸载 App 或调整仓库范围卸载后所有连到该安装的工作区都停止接收事件。下一步可参考 GitHub integration 文档 的 Next stepsIssues 文档讲状态流转与 merge-to-Done 的关系Project resources 文档讲 agent 运行时使用哪些仓库。【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考