常见问题
排查 GitHub PAT 验证失败、OAuth 缺少刷新令牌、仓库不可见、组织审批和 MCP 调用问题。
先判断失败发生在保存连接、读取目标资源，还是调用 MCP 工具，再检查对应配置。
PAT 录入提示凭证无效
检查是否复制了完整 PAT、是否到期或已撤销、是否误加 Bearer ，以及是否把其他 GitHub 实例的 Token 填入 GitHub.com 连接。EasyXAI 会先读取 https://api.github.com/user，身份验证失败不会保存。
当前身份读取没有要求必须添加 read:user 或细粒度 Profile 权限，不要照搬 CNB 的 account-profile:r。PAT 可以通过身份验证，却缺少实际仓库权限。详见PAT 身份验证说明。
OAuth 提示缺少刷新令牌
当前 EasyXAI OAuth 回调必须收到 refresh_token。 如果缺少，连接不会保存，也不会因重复点击“验证”而修好。
- 确认选择的是预期授权客户端，Client ID 与 Client Secret 属于同一个应用。
- 按本指南使用 GitHub App 时，保留 Expire user authorization tokens；已有应用可检查 Optional Features → User-to-server token expiration 是否启用。
- 修改后，从 EasyXAI 重新发起授权，不能继续复用之前的授权结果。
GitHub 最新文档已说明 OAuth App 也可以配置可过期令牌或请求 offline_access。因此，后端旧台账中“只有 GitHub App 返回刷新令牌”的说法已过时；真正的判断依据是本次授权响应是否提供刷新令牌。本指南使用项目既有的 GitHub App 路线，其他 OAuth App 配置需要管理员验证完整授权与续期流程。见 OAuth App 可过期令牌说明。
OAuth 回调地址错误，或返回后没有连接
确认 GitHub 中的 Redirect URI / Callback URL 与部署管理员提供的地址一致，包括协议、域名和 /v1/asset/integration/oauth/callback 路径。
不要把 Homepage URL、Setup URL 或 Webhook URL 当作授权回调。授权应从 EasyXAI 发起；直接打开回调地址、手动复制授权码或重用旧授权链接不能替代正常流程。
账号正常，但私有仓库返回 403 或 404
403 不一定只有一个原因；私有仓库无权访问时也可能返回 404，不能据此断定仓库不存在。
| 连接方式 | 优先检查 |
|---|---|
| 细粒度 PAT | Resource owner、所选仓库、Contents / Issues / Pull requests 等权限，以及组织审批是否仍为 Pending |
| Classic PAT | 私有仓库所需 repo、组织是否允许 classic Token、是否完成对应组织的 SSO 授权 |
| GitHub App OAuth | App 是否安装到目标组织和仓库、所需权限是否获批、授权成员是否本来就有仓库权限 |
| 所有方式 | 当前能力是否使用正确的个人或共享连接，目标链接与仓库路径是否准确 |
组织使用 SSO、IP 访问策略或应用管理策略时，请组织管理员确认运行环境是否被允许访问。账号本人能在浏览器打开仓库，也不代表当前 Token 或应用具有相同范围。
细粒度 PAT 没有 Repositories 权限选项
检查 Repository access。选择 Public repositories 时，界面可能只显示 Account 权限；接入指定私有仓库应选择 Only select repositories，选好仓库后在 Permissions → Repositories → Add permissions 配置。
如果目标 MCP 工具确实不支持细粒度 Token，请核对该工具和 GitHub 接口的支持说明，再使用组织允许的其他方式，不能用添加无关权限解决。相关限制见 GitHub PAT 文档。
已创建 GitHub App，仍然看不到仓库
创建应用只得到配置和凭证，还需要 Install App 安装到资源所属账号并选择仓库，再让成员从 EasyXAI 授权。安装到个人账号，不会自动覆盖同一人加入的组织仓库。
GitHub App 权限在 GitHub 后台设置。EasyXAI 通用“权限范围”字段和连接详情中的 scope，不是应用实际权限证明；不要仅通过填写 repo 来尝试扩大 GitHub App 权限。
连接成功，但智能体没有 GitHub 工具
检查 GitHub 是否在当前工作空间安装并启用、应用能力中是否有已启用 MCP，以及智能体的资源 → 连接的应用是否添加了 GitHub。
还要在“应用能力”的 MCP 旁选择账号并确认「绑定成功」。 从应用详情完成 OAuth 或 PAT 只会保存账号连接，不会自动把它绑定到所有能力；只有一条连接时也需要明确绑定。
MCP 的工具集可能限制只读操作或某类任务。需要凭据的 MCP 在尚未连接账号时，工具发现也可能失败；先配置账号，再检查工具列表和运行记录。仅有 GitHub 连接不代表所有官方 MCP 工具均已开放。
可以读取，但无法评论或修改
检查对应写权限、运行账号权限及工具是否为只读。GitHub 的评论权限模型与 CNB 不同，不存在本指南需要填写的 repo-notes:rw。
仓库保护规则也可能限制直接提交、合并或更新分支。按仓库允许的协作流程执行，不要为了一个失败调用直接勾选全部管理权限。
资源库外部数据源里找不到 GitHub
这是当前支持范围：GitHub 通过 MCP 应用能力使用，尚未提供资源库外部数据源。请按使用指南配置智能体，不需要反复重新授权来寻找数据源入口。
Token 到期、更换客户端密钥或撤销授权
PAT 使用已有连接的重新连接 → 使用访问令牌更新。OAuth 则从原连接重新发起授权；管理员轮换 Client Secret 后，受影响连接若无法续期，也应重新授权验证。
修复 OAuth 原连接时，请在 GitHub 授权页使用原账号。选择另一账号可能形成另一条连接，原 MCP 绑定不会自动切换，需要重新选择并绑定。PAT 原地换令牌则会让所有依赖该连接的能力使用新凭据，提交前核对账号。原 OAuth 客户端停用或归档的处理见凭据更新说明。
仅删除 EasyXAI 中的连接，不等于撤销 GitHub 的 PAT 或授权。反过来，在 GitHub 撤销凭据后，EasyXAI 中依赖它的能力也会失效。