自托管 Git 代码托管

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

仅适用于自部署的 Multica。 此集成只在你自己部署 Multica 时可用，Multica 云端不提供。这里的「自托管」指的是 Multica 本身自部署——通常是为了让它能访问你自己网络内的 Git 实例。需要服务端运维开启（MULTICA_VCS_INTEGRATION_ENABLED=true）并设置 MULTICA_VCS_SECRET_KEY；在此之前，设置 → 集成里不会出现该板块。

Multica 按工作区连接自托管的 Git 代码托管：Forgejo、Gitea 或 GitLab。连接后，任何在分支名、标题或正文中包含 issue 编号（例如 MUL-123）的 Pull Request（GitLab 为 Merge Request）都会自动关联到对应的 issue，出现在 issue 侧栏的 Pull requests 中；当带有关闭关键字的 PR 合并后，issue 会被移动到「完成」。head commit 的 CI 会以检查条的形式显示在卡片上。

这些代码托管与 GitHub 并行工作：一个工作区可任意组合使用。

与 GitHub 不同，这些代码托管没有「App」模型。每个工作区保存自己的实例地址和访问令牌，并在其仓库或组织上注册 Webhook。令牌和 Webhook 密钥均加密存储。

前置条件（服务端）

先为该部署开启此集成。它默认关闭，未开启时该板块不会出现：

MULTICA_VCS_INTEGRATION_ENABLED=true

官方自部署 docker compose 文件（docker-compose.selfhost.yml）已为你设置好。

再设置一个 base64 编码的 32 字节密钥，供服务端加密存储的凭据。未设置时，连接表单将不可用。

openssl rand -base64 32

MULTICA_VCS_SECRET_KEY=<base64 32 字节密钥>

两者都必需：开关决定是否提供该功能，密钥用于加密存储的令牌与 Webhook 密钥。连接、Webhook、轮换都要求两者同时满足。

设置 MULTICA_PUBLIC_URL 为服务端的公网基础地址，Multica 即可直接给出可粘贴的 Webhook 地址；否则界面只显示 Webhook 路径，需自行拼接来源地址。

连接工作区

在代码托管中创建具备仓库读取权限的访问令牌：
- Forgejo / Gitea：设置 → 应用。
- GitLab：具备 read_api 权限的个人（或群组/项目）访问令牌。
在 Multica 中打开 设置 → 集成 → Git 代码托管。
选择提供方，填写实例地址（例如 https://forgejo.example.com）和访问令牌，点击连接。Multica 会先用该令牌访问实例进行校验，再保存。
复制连接后显示的 Webhook 地址 与 Webhook 密钥。

Webhook 密钥只显示一次，请在离开页面前复制。重新连接同一实例会轮换令牌与密钥。

注册 Webhook

在仓库（或组织/群组，以覆盖所有仓库）：

Forgejo / Gitea —— 设置 → Webhook → 添加 Webhook → Forgejo/Gitea：

目标 URL：上一步的 Webhook 地址。
HTTP 方法 POST，内容类型 application/json。
密钥：Webhook 密钥（用于校验 X-Gitea-Signature HMAC）。
触发事件：勾选 Pull Request，并勾选 Commit Status 以镜像 CI。

GitLab —— 设置 → Webhooks：

URL：Webhook 地址。
Secret token：Webhook 密钥（作为 X-Gitlab-Token 发送并逐字比对）。
触发器：启用 Merge request events，并启用 Pipeline events 以镜像 CI。

Multica 会用存储的密钥校验每次投递，因此没有匹配密钥的 Webhook 会被拒绝。

镜像的内容

Pull / Merge Request —— open、closed、merged、draft 状态，以及作者、分支和（在代码托管提供时）diff 统计。
issue 关联 —— 标题、正文或分支中的编号会将 PR 关联到 issue。合并的 PR 带有关闭关键字（Closes/Fixes/Resolves MUL-123）且没有仍处于 open 的关联 PR 时，issue 会被移动到「完成」。
CI —— Forgejo/Gitea 的提交状态与 GitLab 的流水线会汇总为 head commit 的通过/失败/进行中检查条。

智能体创建 Pull Request

创建 PR 无需在 Multica 中进行任何代码托管配置。智能体在运行时中检出仓库，并使用运行时主机自身的 Git 凭据推送分支和创建 PR。要让智能体在某个代码托管上工作，确保 daemon 主机能对其完成认证即可——例如 SSH 部署密钥，或主机 Git 凭据助手中的令牌——再像往常一样添加仓库地址。仓库检出支持任意 Git URL，因此无需提供方专属配置。