企业官网建设流程全解析

自建 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 的部署。

开始前的准备

1. Multica 服务已经启动并可登录，工作区里已有 issue；连接操作需要workspace owner 或 admin身份，普通成员只能查看连接状态。
2. GitHub 能通过 HTTPS 访问你的 API 主机。App 的 Setup URL 和 Webhook URL 都指向 API 地址（下文记作<api-host>，替换为你的 API 域名，例如api.example.com）。如果还是localhost:8080，GitHub 无法回调，需要先按 quickstart 配置反向代理和公网域名。
3. 明确一个长期保存的随机字符串，作为 Webhook secret。注意这是Webhook secret，不是 App 的 OAuth Client secret；两边不一致时 GitHub 投递会返回401 invalid signature。

第 1 步：在 GitHub 创建 App

在 GitHub 的Developer settings → GitHub Apps中创建 App，按下表填写：

仓库权限（Repository permissions）：

事件订阅（Subscribe to events）：

• Pull request；
• Check suite、Check run、Status，用于触发 CI 和 mergeability 刷新。

如果你不需要在 Multica 里显示 CI，可以跳过 Checks 和 Commit statuses 这两项权限及对应事件。但Contents 不能省——没有它 snapshot 查询会直接失败，PR 卡片上的 merge 状态也会丢失。

创建完成后记下三样东西：App 的slug（App 公开 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.example）：

GITHUB_APP_SLUG=multica-acme GITHUB_WEBHOOK_SECRET=<第 1 步填入 App 的那个 webhook secret> FRONTEND_ORIGIN=https://multica.example.com

其中GITHUB_APP_SLUG和GITHUB_WEBHOOK_SECRET是最低要求：两者任一缺失，Connect GitHub 按钮会保持禁用，webhook 端点也会拒绝处理事件。FRONTEND_ORIGIN是自建部署的必选项，这里填用户访问的前端 origin。

如果还希望 PR 卡片显示 CI 状态和 mergeability，再补两个变量——Multica 用它们以 App 身份认证并拉取 GitHub API 快照：

GITHUB_APP_ID=<App 设置页上的数字 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 里完成连接

1. 打开Settings → GitHub。
2. 打开 GitHub integration 主开关。
3. 点击Connect GitHub，会跳转到 GitHub。
4. 在 GitHub 上选择账户或组织，授权全部仓库或自选一部分仓库。
5. 安装完成后回到 Multica，连接状态显示在同一页面。

页面上的四个开关各司其职：GitHub integration是主开关（关闭时下面三项停摆，但 App 保持已连接）；PR sidebar控制 issue 详情里是否展示已关联 PR；Co-authored-by会给 agent 生成的 commit 追加Co-authored-by: multica-agent <github@multica.ai>；Auto-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-redirect

MUL-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”从不被当作通过），以及 mergeability（mergeable/conflicting/blocked/behind）。点击条目可打开 GitHub 上的 PR。CI 和 mergeability 来自 Multica 从 GitHub API 拉取的快照，两者相互独立；已合并或关闭的 PR 不再显示；GitHub 暂时不可用时卡片保留上次快照并标记为 stale，而不是变空白。

合并后的流转规则同样值得核对：Multica 只在全部满足下列条件时把 issue 移到Done：

1. 至少一个已合并的关联 PR 使用了 close intent 且标识紧跟其后（例如Closes MUL-123；中间夹了其他词的写法如Closes login MUL-123不算）；
2. 该 issue 没有其他仍处于Open或Draft的有效关联 PR（正文中的普通提及不算）；
3. issue 当前不是done或cancelled。

所以只在分支名或标题里写MUL-123只建立关联、不触发完成；PR 未合并就被关闭也不完成 issue。状态变更会作为系统动作写入时间线，并通知订阅了该 issue 的成员。

常见排查项

文档列出的排查对照：

边界与断开

• 同一套 GitHub App 安装可以连接多个 Multica 工作区，GitHub 事件分别流入各工作区，并与各自工作区的 issue 前缀匹配；工作区之间互不可见对方的 issue。
• 在Settings → GitHub点Disconnect只解除当前工作区与这次安装的关系，不会替你从 GitHub 卸载 App；已有 PR 记录保留，新事件停止流入该工作区。要在 GitHub 侧收回仓库授权，需要从个人或组织的 GitHub App installations 页卸载 App 或调整仓库范围；卸载后所有连到该安装的工作区都停止接收事件。

下一步可参考 GitHub integration 文档 的 Next steps：Issues 文档讲状态流转与 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