Multica Docs

GitHub 集成

把 pull request 与 Multica issue 关联，并在 issue 中查看开发进展。

连接 GitHub 后，Multica 根据 issue 编号自动关联 pull request。issue 详情中可直接查看 PR 状态、改动规模、CI 结果和合并冲突。

GitHub 集成只读取安装时授权的仓库，不会提交代码、评论或 status check。

自部署的 Multica 还可以并行连接自托管的 Forgejo、Gitea 或 GitLab 实例，获得同样的 PR 自动关联、合并转 Done 和 CI 展示，入口在 设置 → 集成 → Git 代码托管，详见自托管 Git 代码托管。Multica Cloud 不提供该入口。

连接 GitHub

工作区 owner 或 admin 可以完成连接：

  1. 打开 设置 → GitHub。
  2. 打开 GitHub 集成总开关。
  3. 点击 连接 GitHub。
  4. 在 GitHub 中选择账号或组织，并授权全部仓库或指定仓库。
  5. 安装完成后回到 Multica。

连接状态会显示在同一页面。普通成员可以查看状态，但不能连接、断开或修改开关。

GitHub 连接决定 Multica 从哪些仓库接收 PR 事件；代码仓库设置决定智能体执行任务时可以选择哪些仓库。两者用途不同，需要分别配置。

功能开关

设置 → GitHub 中有四个开关：

开关作用
GitHub 集成总开关。关闭后，下面三项不再生效，但不会断开 GitHub App。
PR 侧栏在 issue 详情中显示关联的 pull request。
Co-authored-by在智能体创建的 commit 中加入 Co-authored-by: multica-agent <github@multica.ai>。
自动关联 PR从 PR 的分支名、标题和正文中识别 issue 编号。
PR 卡片 → CI 与可合并性对每个关联的 PR，Multica 从 GitHub API 拉取一份经鉴权的快照，把它的 CI 状态和可合并性镜像到卡片上（见下方 PR 卡片展示什么）。

让 PR 关联到 issue

最简单的做法，是把 issue 编号写进分支名或 PR 标题。例如 issue 为 MUL-123：

mul-123-fix-login-redirect
MUL-123 修复登录后的跳转

Multica 会忽略大小写，并且只匹配当前工作区的 issue 前缀。一个 PR 可以关联多个 issue。

只在 PR 正文中写编号时，需要使用 GitHub 的关闭语句：

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

正文中的普通提及，例如 Related to MUL-123，不会作为该 issue 的工作 PR 显示。Commit message 和 PR 评论也不会触发关联。

在 issue 中查看 PR

关联成功后，PR 会出现在 issue 详情的 Pull requests 区块。每条记录会显示：

  • 仓库、编号、标题和作者；
  • Open、Draft、Merged 或 Closed 状态；
  • 新增、删除行数和改动文件数；
  • CI 状态：全部通过（带计数）、若干个失败（点名失败的 check），或若干个进行中；没有配置任何 check 的 PR 不显示这一项，"没有 check"不会被当成通过；
  • 可合并性：可合并（仅当 GitHub 报告合并状态为 clean）、有冲突、blocked 或 behind。

CI 状态和可合并性来自 Multica 从 GitHub API 拉取的快照，两者互相独立；已合并或已关闭的 PR 不再显示这两项。GitHub 暂时不可用时，卡片会保留上一次的快照并标记为过期，而不是清空。

点击记录可以打开 GitHub 上的 PR。关闭 PR 侧栏 只会隐藏这个区块，不会断开连接。

PR 合并转 Done 的条件

PR 合并不一定代表 issue 已完成。Multica 只有在以下条件同时成立时，才把 issue 改为 Done：

  1. 至少一个已合并的关联 PR 使用了紧跟编号的关闭语句，例如 Closes MUL-123（Closes login MUL-123 这类中间隔词的写法不生效）；
  2. 该 issue 没有其他仍为 Open 或 Draft 的工作 PR（正文中的普通提及不算）；
  3. issue 当前不是 done 或 cancelled。

因此，仅在分支名或标题中写 MUL-123 会建立关联，但不会单独触发完成。PR 关闭但没有合并，也不会完成 issue。

状态变化会以系统操作写入时间线，订阅该 issue 的成员会收到通知。

多个工作区

同一个 GitHub App installation 可以连接到多个 Multica 工作区。GitHub 事件会分别进入每个工作区，再按照各自的 issue 前缀匹配。

例如一个 PR 同时引用 MUL-1 和 ENG-2，它可以在两个不同前缀的工作区中分别关联。工作区之间不会看到对方的 issue。

断开连接

在 设置 → GitHub 点击 断开，只会移除当前 Multica 工作区与该 installation 的关系，不会替你从 GitHub 卸载 App。已有 PR 记录会保留，新的事件不再进入该工作区。

撤销 GitHub 侧的仓库授权，需到个人或组织的 GitHub App installations 页面卸载或调整仓库范围。卸载后，与该 installation 关联的所有 Multica 工作区都会停止接收事件。

自托管配置

Multica Cloud 无需执行本节。自托管需要先创建自己的 GitHub App。

1. 创建 GitHub App

在 GitHub 的 Developer settings → GitHub Apps 中创建 App，并填写：

字段值
Homepage URLMultica 前端地址，例如 https://multica.example.com
Callback URL留空
Setup URLhttps://<api-host>/api/github/setup，并启用 Redirect on update
Webhook URLhttps://<api-host>/api/webhooks/github
Webhook secret一段长期保存的随机字符串

Repository permissions：

权限级别
MetadataRead-only
Pull requestsRead-only
ChecksRead-only；用于显示 CI 状态
Commit statusesRead-only；用于汇总 legacy status 形式的 CI

订阅以下事件：

  • Pull request；
  • Check suite、Check run 和 Status，用于触发 CI 与可合并性刷新。

如果不需要在 Multica 中显示 CI，可以不授予 Checks 和 Commit statuses 权限，也不订阅对应事件。

这里需要的是 Webhook secret，不是 OAuth Client secret。两边填写的 Webhook secret 不一致时，GitHub delivery 会返回 401 invalid signature。

2. 配置环境变量

从 App 的公开地址取得 slug。例如 https://github.com/apps/multica-acme 的 slug 是 multica-acme。

GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<创建 App 时填写的 webhook secret>
FRONTEND_ORIGIN=https://multica.example.com

GITHUB_APP_SLUG 和 GITHUB_WEBHOOK_SECRET 缺少任意一个时，连接按钮会被禁用，webhook 接口也会拒绝处理事件。

下面两个变量是 PR 卡片显示 CI 状态与可合并性的必要条件——Multica 用它们以 App 身份鉴权并拉取快照：

GITHUB_APP_ID=<GitHub App 的数字 ID>
GITHUB_APP_PRIVATE_KEY=<完整 PEM 私钥，保留 BEGIN/END 行和换行>

私钥在 GitHub App 的 Private keys → Generate a private key 中生成。不配置时集成会平稳降级：PR 照常镜像，issue 照常自动关联并在合并时转 Done，只是 PR 卡片不显示 CI 或合并状态。

3. 更新数据库并连接

升级已有部署时，先执行常规数据库迁移：

make migrate-up

重启 API 服务，再到 设置 → GitHub 完成连接。

常见问题

  • 连接按钮不可用：检查 GITHUB_APP_SLUG 和 GITHUB_WEBHOOK_SECRET 是否已进入 API 进程。
  • Webhook 返回 401：确认 GitHub App 与 API 使用同一个 Webhook secret，然后在 GitHub 的 Recent Deliveries 中重新投递。
  • PR 没有关联：检查仓库是否在 App 授权范围内、自动关联是否开启，以及编号是否属于当前工作区。
  • 正文写了编号但没显示：改用 Closes MUL-123，或把编号放到分支名、PR 标题中。
  • 没有 CI 状态：确认 GITHUB_APP_ID 和 GITHUB_APP_PRIVATE_KEY 已配置，App 具有 Checks 与 Commit statuses 的只读权限并订阅了对应事件。给已安装的 App 补加权限后，还需要各 installation 的所有者在 GitHub 上批准才会生效。
  • PR 合并后 issue 没完成：确认 PR 使用了关闭语句，并检查是否还有其他关联 PR 处于 Open 或 Draft。

接下来

  • Issues — 状态流转与 PR 合并转 Done 的关系。
  • 项目资源 — 智能体执行时使用哪些仓库。
  • 环境变量 — 自托管 GitHub App 的完整配置。

钉钉 Bot 接入

把 Multica 智能体接入你自己的钉钉 app——在钉钉开放平台创建一个 Stream 模式的机器人、复制它的 AppKey 与 AppSecret、粘贴进 Multica，然后就能在钉钉里私聊它、在群里 @ 它，或输入 /issue。

自托管 Git 代码托管

为每个工作区连接自托管的 Forgejo、Gitea 或 GitLab 实例，使引用了 issue 编号的 Pull Request / Merge Request 自动关联到对应 issue，在合并时将其移动到「完成」，并展示 CI 状态。

本页目录

连接 GitHub功能开关让 PR 关联到 issue在 issue 中查看 PRPR 合并转 Done 的条件多个工作区断开连接自托管配置1. 创建 GitHub App2. 配置环境变量3. 更新数据库并连接常见问题接下来