# GitHub 配置指南

## 你可以用它做什么

让智能体查询仓库、Issue、PR 等；也可配置 GitHub 事件接收。首次建议从只读查询开始。

## 配置前准备

请仓库负责人确认目标仓库范围。在 GitHub 个人设置的 Developer settings → Personal access tokens 创建适用 Token，优先选择限定仓库和最小所需权限的凭证，并设置有效期。组织可能需要批准。不要为了测试直接授予所有仓库写权限。

需要能够在当前 MOI 工作区创建或编辑工具配置。若没有入口或提示无权操作，请联系工作区管理员，不要借用他人的账号。

## 配置页面


```{figure} /assets/images/agents/guide-5-hd/44-github-api-config.png
:alt: GitHub 仓库 API 访问配置：Access Token 必填，仓库范围按需填写。
:class: agent-guide-image
:figclass: agent-guide-shot

GitHub 仓库 API 访问配置：Access Token 必填，仓库范围按需填写。
```

## 在 MOI 中操作

1. 进入工具市场的 GitHub，先选择 API 调用能力，创建实例。
2. 填写 Access Token；为减少误用，填写准备测试的 Owner 与 Repository。保存并测试连接。
3. 在智能体的工具配置中绑定 GitHub 工具，并选择该实例。先做只读验收。
4. 如需事件触发，再选择 Webhook 能力。填写匹配的 Webhook Secret 与所需字段，保存后从实例详情复制回调 URL。
5. 在目标仓库或组织的 Webhooks 设置中填写该 URL 和相同 Secret，选择真正需要的事件。不要使用 127.0.0.1 作为第三方回调地址。
6. 在 MOI 配置相应事件路由规则及目标智能体/任务，并用测试仓库事件验证。PR Review 场景按页面提示订阅 Check suites、Check runs 等所需事件。

## 字段怎么填写

| 字段 | 何时需要 | 填写说明 |
| --- | --- | --- |
| 实例名称 | 必填 | 例如「产品测试仓库」。 |
| Access Token | 仓库 API 与 Webhook 入口均必填 | 用于实际调用 GitHub API，不能用 Webhook Secret 替代。 |
| Owner / Repository | 可选 | 例如 Owner=example-team、Repository=demo；分别填写，不填完整网址。 |
| App ID / Installation ID | API 入口可选 | 只有确实采用 GitHub App 时才填写；仅填 ID 不能替代 Token。 |
| Webhook Secret | Webhook 入口可选 | 与 GitHub Webhook 配置保持一致，用于验签；不要当成 API Token。 |



```{figure} /assets/images/agents/guide-5-hd/45-github-webhook-config.png
:alt: GitHub Webhook 配置：当前表单 Access Token 必填，Webhook Secret 标记为可选。
:class: agent-guide-image
:figclass: agent-guide-shot

GitHub Webhook 配置：当前表单 Access Token 必填，Webhook Secret 标记为可选。
```

## 让智能体实际使用

回到目标智能体详情，在工具区域检查对应能力是否已绑定；提供实例选择时，核对目标连接。具体步骤见[绑定并验证工具](../bind-tools.md)。

先让智能体「读取 example-team/demo 的最近三个 Issue，只查询，不创建评论」。核对 Issue 链接和工具结果。事件场景另外核对 GitHub delivery 是否成功、MOI 是否接收并触发正确目标；连接测试不能代替事件验收。

验收时逐项确认：

- [ ] 保存成功，重新打开后配置仍存在。
- [ ] 测试连接返回成功，而不是只有「已配置」标签。
- [ ] 对话的工具调用记录显示实际调用，结果与目标平台一致。
- [ ] 如启用事件接收，还验证了事件投递和正确目标触发。

## 常见问题

| 现象 | 检查方法 |
| --- | --- |
| 能连接但查不到仓库 | 检查 Token 仓库范围、组织批准及 Owner/Repository。 |
| 读取成功但写入失败 | 核对目标操作所需权限；只有明确需要写操作时才增加相应权限。 |
| Webhook 不触发 | 检查公网回调、Secret 一致性、事件订阅及 MOI 路由规则，查看 delivery 记录。 |

## 凭证维护与安全

只在 MOI 的敏感字段中输入 Key、Token、密码或私钥，不要放进提示词、截图、Issue 或 Git 仓库。配置更换前先确认有哪些智能体使用该实例；更换后重新测试，再验证一次实际任务。若凭证泄露，应到提供方撤销并生成新凭证。删除或停用配置会影响依赖它的调用，请先确认影响范围。

## 资料与核对范围

- [GitHub Token 官方说明](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)。外部控制台菜单可能随版本变化；以提供方页面为准。
- 接入范围与资料依据见[指南说明](index.md#tool-configuration-sources)。
- [返回工具配置指南目录](index.md)。