GitHub 集成

GitHub 集成通过 Webhook 将你的 GitHub 仓库连接到 Mopheus。当 GitHub 中发生事件（push、Pull Request、Issue、Workflow Run 等）时，Mopheus 接收 Webhook 载荷并将其调度到 Job 进行处理。你还可以注册仓库，让 Agent 能够克隆和操作你的代码。

前置条件

• 已启用 Git 功能标志的 Mopheus 工作区（设置 → 功能）
• 具有管理员权限以配置 Webhook 的 GitHub 仓库
• Mopheus 服务器 URL 必须可公开访问（GitHub 需要能够到达你的 Webhook 端点）
• 主机上已配置 Git 凭据 — SSH 密钥（~/.ssh/id_*）或 HTTPS 凭据管理器，以便守护进程可以 pull/push
• 在 Mopheus 用户资料中配置了 Git 提交身份（设置 → 个人资料）— 作为 Agent 推送代码时的提交作者

设置

1. 启用 Git 功能

Git 集成受功能标志控制。管理员需要启用它：

1. 进入 管理 → 功能
2. 找到 Git 功能，设置为 启用（或 选定 以白名单特定工作区）

2. 注册仓库

在工作区的 设置 → 仓库 中，点击 添加仓库：

3. 创建 Job 和 Webhook 触发器

1. 进入 Jobs 页面，点击 创建 Job
2. 命名 Job 并配置其 Action（处理逻辑）
3. 在 Job 详情页，进入 Webhook 标签页，点击 添加触发器
4. 可选：设置 签名密钥 用于 HMAC-SHA256 签名验证
5. 可选：添加 事件过滤器 以仅接收特定事件（如 pull_request，动作 opened、closed）
6. 复制页面上显示的 Webhook URL

4. 在 GitHub 中配置 Webhook

1. 进入 GitHub 仓库 → Settings → Webhooks → Add webhook
2. 将 Mopheus Webhook URL 粘贴到 Payload URL 字段
3. 将 Content type 设置为 application/json
4. 如果你在 Mopheus 中设置了签名密钥，在 Secret 字段输入相同的值
5. 选择要发送的事件：
   • Just the push event — 仅 push 触发
   • Let me select individual events — 精细控制（推荐）
   • Send me everything — 接收所有事件
6. 点击 Add webhook

工作原理

Webhook 处理流程

GitHub 发送 Webhook POST
        │
        ▼
Mopheus 在 /api/v1/webhooks/jobs/{token} 接收
        │
        ├─ 限流（IP + Token）
        ├─ Token 查找 → 定位触发器
        ├─ 触发器启用检查
        ├─ 请求体大小检查（最大 10 MiB）
        ├─ 签名验证（如配置了密钥）
        ├─ 去重（30 秒窗口）
        │
        ▼
从 X-GitHub-Event Header 提取事件类型
        │
        ▼
向载荷注入 _eventType 元数据
        │
        ▼
调度 Job → Agent 或 Action 处理事件

事件规范化

GitHub 事件被规范化为 {provider}.{event}.{action} 格式：

事件过滤器

创建 Webhook 触发器时，最多可添加 5 个事件过滤器。每个过滤器包含：

• 事件：事件名称（如 pull_request、push、issues）
• 动作（可选）：要匹配的动作列表（如 opened、closed、synchronize）

如果未设置过滤器，所有事件都会通过。如果设置了过滤器，传入事件必须匹配至少一个过滤器的事件名称，且如果该过滤器有动作列表，传入动作必须匹配其中之一。

动作候选值从事件后缀和已知载荷字段（action、state、conclusion、status）中提取。

签名验证

Mopheus 支持 HMAC-SHA256 签名验证，兼容 GitHub 的 Webhook 签名方案。

工作方式

1. 当你在 Webhook 触发器上设置 签名密钥 后，Mopheus 会要求每个请求都包含签名 Header
2. 签名计算方式：sha256=<hex(hmac_sha256(body, secret))>
3. Mopheus 按以下顺序检查 Header：
   • X-Webhook-Signature（通用）
   • X-Hub-Signature-256（GitHub 专用）
4. 验证状态记录在每次 Job 运行中（signature_status）：valid、invalid、missing 或 not_required

设置步骤

1. 生成随机密钥字符串（如 openssl rand -hex 32）
2. 在 Mopheus 中：Job 详情 → Webhook 标签页 → 设置 签名密钥
3. 在 GitHub 中：仓库 → Settings → Webhooks → 在 Secret 字段输入相同的值

去重

Mopheus 在两个层面去重 Webhook 事件：

内存层（30 秒窗口）

第一道防线。优先使用提供者特定的投递 ID：

要重放被抑制的事件，在请求中设置 X-Mopheus-Replay: true Header。

数据库层

(trigger_id, dedupe_key) 上的唯一索引防止重复 Job 运行被记录。attempt_count 列跟踪同一去重 key 被接收的次数。

限流

Webhook 端点有两层限流：

被限流时，端点返回 429 Too Many Requests，并附带 Retry-After: 1 Header。

Git 实体同步

Mopheus 可以镜像 GitHub 的 Pull Request 和 Issue，并将它们链接到工单。

同步内容

Pull Request：编号、标题、状态、head/base ref、作者、合并状态、关闭关键词、新增/删除/变更文件数。

Issue：编号、标题、状态、作者。

工单链接

当 PR 或 Issue 链接到工单时，Mopheus 会跟踪 close_intent 标志。这支持自动化场景，如"当此 PR 合并时，关闭关联的工单"。

内置 Agent 技能

Mopheus 内置两个技能供 Agent 与 GitHub 交互。在启用了 Git 功能的工作区中运行的任何 Agent 都可以使用这些技能。

代码工作流（mopheus-github-repos）

需要编写或修改代码时使用。覆盖完整的 checkout → 编码 → commit → push → PR → 同步 流程。

# 1. Checkout — 创建隔离的 worktree
mopheus repo checkout <url> --output json

# 2. 编码 — cd 到返回的路径，进行修改

# 3. Commit — conventional 格式
git add -A && git commit -m "fix: description"

# 4. Push
git push -u origin <branch-name>

# 5. 创建 PR
gh pr create -R <url> --title "..." --body "..." --base main

# 6. 同步 PR 到工单（必须）
mopheus repo pr sync --repo <url> --number <N> --title "..." --state open --ticket <ticket-id> --auto-link --output json

关键规则：

• 始终使用 mopheus repo checkout，不要直接用 git worktree add。守护进程维护裸仓库缓存，为每个 Agent 任务创建隔离的 worktree。
• Worktree 分支名为 agent/<name>/<task-id>，不要重命名。
• 使用 --ref <branch|sha> 来 checkout 非默认分支。
• 现有 worktree 包含本地改动或未推送提交时会受到保护。仅在确定要丢弃这些内容时使用 --force。
• 始终在 mopheus 命令上使用 --output json，以便结果可被机器解析。
• 不要跳过第 6 步。已 push 但未同步 PR 的分支对工单不可见。

Webhook 事件处理（mopheus-github-webhook）

收到 GitHub Webhook 事件后使用。覆盖 PR/Issue 同步、工单关联、自动关闭和自动创建流程。

issues 和 pull_request 事件仅处理三种动作：opened、closed 和 reopened。所有其他动作（labeled、assigned、synchronize 等）会被跳过。

工作流程：

1. 识别仓库 — mopheus repo list --output json，与载荷中的 repository.html_url 匹配
2. 检查实体是否已存在 — mopheus repo pr list 或 mopheus repo issue list
3. 同步实体 — mopheus repo pr sync 或 mopheus repo issue sync，使用 --auto-link
4. 评估自动关闭 — 当 PR 合并且包含 --close-keyword 或 Issue 关闭时，检查所有关联 PR 是否已完成且工单未处于终态 → 将工单设为完成

自动关联： --auto-link 标志匹配 PR/Issue 标题和正文中的工单标识符（如 MOPHEUS-42）。匹配成功时自动创建关联。

自动创建： 当工作区设置 auto_create_tickets 启用且未匹配到工单标识符时，技能会从 Webhook 载荷创建新工单并关联到实体。

CLI 命令

使用 mopheus CLI 在终端管理 Job 和触发器：

# 创建 Webhook Job
mopheus job create --name "GitHub PR Handler" --trigger-type webhook --action-type agent

# 为现有 Job 添加 Webhook 触发器
mopheus job trigger-add <job-id> --kind webhook

# 列出 Job 的触发器
mopheus job trigger-list <job-id>

# 轮换 Webhook Token（使旧 URL 失效）
mopheus job trigger-rotate-url <job-id> <trigger-id>

# 手动触发 Job
mopheus job trigger <job-id>

# 查看运行历史
mopheus job runs <job-id>

仓库管理 CLI

# 注册仓库（URL 为位置参数，provider 自动识别）
mopheus repo add https://github.com/owner/repo

# 列出已注册仓库
mopheus repo list

# 移除仓库
mopheus repo remove https://github.com/owner/repo

# 为 Agent 任务创建隔离的 worktree
mopheus repo checkout https://github.com/owner/repo

# 关联 / 取消关联 PR 或 Issue 到工单（实体关联，不是仓库注册）
mopheus repo link --ticket <ticket-id> --entity-type git_pull_request --entity <entity-uuid>
mopheus repo unlink --ticket <ticket-id> --entity-type git_pull_request --entity <entity-uuid>

repo add / repo remove 用于注册仓库；repo link / repo unlink 用于把已同步的 PR 或 Issue 实体关联到工单——两者是不同操作，不要混淆。

故障排查