配置 GitHub App 与 OAuth 授权
创建 GitHub App，配置 OAuth 回调与权限，安装到目标仓库，再在 EasyXAI 登记客户端并连接账号。
本页通过 GitHub App 的用户 OAuth 授权接入。已有可用平台默认或团队客户端的成员，可直接跳到连接自己的 GitHub 账号。使用 PAT 请阅读个人访问令牌指南。
保留 Expire user authorization tokens 勾选。 EasyXAI 当前 OAuth 回调要求获得刷新令牌；授权响应缺少
refresh_token时，连接不会保存。创建应用、安装到仓库、成员授权是三个不同步骤。
1. 创建 GitHub App
由应用负责人打开 Settings → Developer settings → GitHub Apps → New GitHub App。个人账号可直接打开创建页面；应用归组织管理时，从该组织的 Settings 进入。
| 字段 | 填写内容 |
|---|---|
| GitHub App name | 可识别的团队应用名称，在 GitHub 上需要唯一 |
| Description | 简述用于 EasyXAI 的仓库、Issue、PR 访问 |
| Homepage URL | 团队的 EasyXAI 首页或实际介绍页面 |
图 1：未提交的示例应用，example.com 仅用于展示格式。请填写真实名称与网站。
2. 配置回调和令牌设置
在 Identifying and authorizing users 中，将 Redirect URI（部分界面称 Callback URL）设为当前 EasyXAI 部署的完整回调地址：
https://<当前环境的回调域名>/v1/asset/integration/oauth/callback回调域名由部署管理员提供，可能与前端域名不同。不要填写 GitHub 仓库地址、EasyXAI 资源库页面或登录页。使用完整地址即可，无需开启通配符匹配。
图 2：Redirect URI 使用示例域名，实际接入必须替换。令牌过期选项已开启；安装时授权与 Device Flow 均未开启。
| 设置 | 本指南配置 |
|---|---|
| Expire user authorization tokens | 保持开启，让 GitHub 返回刷新令牌 |
| Request user authorization (OAuth) during installation | 本流程保持关闭；先安装应用，再由成员从 EasyXAI 发起授权 |
| Enable Device Flow | 无需开启，本页使用浏览器跳转授权 |
| Setup URL / Redirect on update | 本流程无需配置 |
| Webhook → Active | 仅用于本指南的授权与 MCP 调用时可关闭，无需填写 Webhook URL |
GitHub App 的用户访问令牌到期后可由刷新令牌续期；刷新令牌过期或授权撤销时仍需重新授权。设置说明见 GitHub App 注册指南与令牌刷新说明。
3. 配置权限和可安装范围
展开 Permissions → Repository permissions。首次接入以读取任务验证，可按下表配置。
| 权限 | 初次读取配置 | 说明 |
|---|---|---|
| Contents | Read-only | 读取代码、提交和分支 |
| Issues | Read-only | 读取议题及相关评论 |
| Pull requests | Read-only | 读取 PR 与变更 |
| Metadata | Read-only | 仓库元信息，通常随仓库权限自动要求 |
| Actions（可选） | Read-only | 需要查询工作流运行时再添加 |
需要创建 Issue、评论或修改代码时，按目标操作选择相应 Read & write。应用权限与成员自己的权限共同决定可执行的操作，不会因安装应用而自动提升成员权限。见 GitHub 用户授权说明。
在 Where can this GitHub App be installed? 中选择范围：应用直接建在目标组织且仅供该组织使用时可选 Only on this account；需要安装到其他账号或组织时选择 Any account。确认后点击 Create GitHub App。Any account 表示可被安装，并不等于已获得任何组织的仓库访问权。
4. 安装到目标账号和仓库
在刚创建的应用设置页，进入 Install App，在目标个人或组织旁点击 Install。选择 Only select repositories，选中需要访问的仓库，再完成安装；组织要求审批时，请管理员处理。
以后访问新仓库，需要检查是否已加入该安装的仓库范围。操作入口与范围规则见 安装自己的 GitHub App。
安装应用与授权自己的账号不能相互替代。 安装用于授予应用访问目标资源的范围；成员还要从 EasyXAI 完成下方的 OAuth 授权。私有资源访问同时受应用权限、安装范围与成员权限限制。
5. 取得凭证并登记到 EasyXAI
在 GitHub App 设置中找到 Client ID，在 Client secrets 中生成客户端密钥（Generate a new client secret），由工作空间管理员填写到 EasyXAI。
Client ID 不等于 App ID；Client Secret 不等于私钥、Webhook Secret 或 PAT。 本流程不要求上传 .pem 私钥。相关凭据用途见 GitHub App 用户访问令牌说明。
- 进入目标工作空间的资源库 → 扩展 → 应用中心 → GitHub。
- 如未安装，由管理员点击安装到本团队。
- 打开自带授权应用 → 添加应用，按下表填写并保存。
图 3：示例未保存，Client ID 不可直接使用。首次保存必须填写真实 Client Secret。
| EasyXAI 字段 | 填写说明 |
|---|---|
| 名称 | 例如 团队 GitHub App |
| Client ID | 刚创建的 GitHub App 的 Client ID |
| Client Secret | 对应的客户端密钥 |
| 权限范围 | 本指南保持留空，继承当前连接器默认配置；实际 GitHub App 权限在 GitHub 后台设置 |
不要把 Contents、Issues、Pull requests 填到“权限范围”文本框。 GitHub App 使用细粒度权限，不通过传统 repo、read:org 等 scope 授予仓库权限。EasyXAI 的该字段是通用配置：留空表示继承默认，填写后会整体覆盖；即使连接详情显示继承的 scope，也不能将其视为 GitHub App 实际权限的证明。见 GitHub 权限模型说明。
保存后确认客户端处于启用中。编辑时 Client Secret 留空表示保留原密钥；普通成员看不到此页签时，由工作空间管理员处理。
6. 连接自己的 GitHub 账号
- 在应用中心 → GitHub → 连接账号中点击连接账号。
- 如有多个授权客户端，选择团队指定的应用，再点击一键授权；只有单一方式时可能显示前往授权。
- GitHub 页面中确认登录账号、应用名称和访问说明，完成 Authorize。
- 回到 EasyXAI，在应用中心 → 我的连接核对账号，再点击验证。
图 4：OAuth 流程选择“一键授权”。截图仅展示入口，未执行新的授权。
授权须从 EasyXAI 发起以完成回跳。无需复制授权码、手工拼接 URL 或把 OAuth 返回的访问令牌粘贴成 PAT。
7. 验证实际使用
继续为智能体添加 GitHub，读取一条已知 Issue 或 PR。依次核对客户端启用、账号正确、目标仓库在安装范围内、MCP 调用成功。
若报“缺少刷新令牌”，首先检查 Expire user authorization tokens 与客户端类型，再重新从 EasyXAI 授权。GitHub 最新官方文档也提供了 OAuth App 的可过期令牌机制；本页沿用项目既有的 GitHub App 接入方式，不能把“普通 OAuth App 永远不支持刷新”当作判断依据。详见排查说明。