EasyXAI 文档
连接器GitHub

配置 GitHub App 与 OAuth 授权

创建 GitHub App,配置 OAuth 回调与权限,安装到目标仓库,再在 EasyXAI 登记客户端并连接账号。

本页通过 GitHub App 的用户 OAuth 授权接入。已有可用平台默认或团队客户端的成员,可直接跳到连接自己的 GitHub 账号。使用 PAT 请阅读个人访问令牌指南。

  1. 创建 GitHub App

    前往创建 GitHub App

    打开下方页面,填写应用名称和 Homepage URL(团队网站或 EasyXAI 首页)。

    团队共用时,先确认应用应建在个人账号还是组织下。

  2. 填写登录后的返回地址

    向 EasyXAI 部署管理员索取完整回调地址,填入 Redirect URI / Callback URL。

    完整域名必须使用管理员提供的值,不要自行拼接。

    保留 Expire user authorization tokens 勾选,才能让账号在令牌到期后继续使用。

  3. 设置读取权限并选择仓库

    在 Repository permissions 中按用途选 Read-only。

    创建应用后,打开 Install App,在目标账号旁点击 Install,再选择允许访问的仓库。

    用途权限要求
    读取文件、提交和分支Contents按需
    读取 Issue 及相关评论Issues按需
    读取 PR 与代码变更Pull requests按需
    读取仓库基本信息,通常自动添加Metadata按需
  4. 复制 Client ID 和 Client Secret

    在应用设置中复制 Client ID,在 Client secrets 点击 Generate a new client secret。

    按下表填写,权限范围留空,然后保存。

    Client ID
    填入 Client ID
    Client Secret
    填入 Client Secret

1. 创建 GitHub App

由应用负责人打开 Settings → Developer settings → GitHub Apps → New GitHub App。个人账号可直接打开创建页面;应用归组织管理时,从该组织的 Settings 进入。

字段填写内容
GitHub App name可识别的团队应用名称,在 GitHub 上需要唯一
Description简述用于 EasyXAI 的仓库、Issue、PR 访问
Homepage URL团队的 EasyXAI 首页或实际介绍页面

GitHub App 创建页中的名称、描述和首页地址

图 1:未提交的示例应用,example.com 仅用于展示格式。请填写真实名称与网站。

2. 配置回调和令牌设置

在 Identifying and authorizing users 中,将 Redirect URI(部分界面称 Callback URL)设为当前 EasyXAI 部署的完整回调地址:

https://<当前环境的回调域名>/v1/asset/integration/oauth/callback

回调域名由部署管理员提供,可能与前端域名不同。不要填写 GitHub 仓库地址、EasyXAI 资源库页面或登录页。使用完整地址即可,无需开启通配符匹配。

GitHub App 回调地址示例,Expire user authorization tokens 保持勾选

图 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。首次接入以读取任务验证,可按下表配置。

权限初次读取配置说明
ContentsRead-only读取代码、提交和分支
IssuesRead-only读取议题及相关评论
Pull requestsRead-only读取 PR 与变更
MetadataRead-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 用户访问令牌说明。

  1. 进入目标工作空间的资源库 → 扩展 → 应用中心 → GitHub。
  2. 如未安装,由管理员点击安装到本团队。
  3. 打开自带授权应用 → 添加应用,按下表填写并保存。

EasyXAI 添加 GitHub 自带授权应用表单,Client ID 为示例,密钥和权限范围留空

图 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 账号

  1. 在应用中心 → GitHub → 连接账号中点击连接账号。
  2. 如有多个授权客户端,选择团队指定的应用,再点击一键授权;只有单一方式时可能显示前往授权。
  3. GitHub 页面中确认登录账号、应用名称和访问说明,完成 Authorize。
  4. 回到 EasyXAI,在应用中心 → 我的连接核对账号,再点击验证。

EasyXAI 连接 GitHub 账号时选择一键授权或使用访问令牌

图 4:OAuth 流程选择“一键授权”。截图仅展示入口,未执行新的授权。

授权须从 EasyXAI 发起以完成回跳。无需复制授权码、手工拼接 URL 或把 OAuth 返回的访问令牌粘贴成 PAT。

7. 验证实际使用

继续为智能体添加 GitHub,读取一条已知 Issue 或 PR。依次核对客户端启用、账号正确、目标仓库在安装范围内、MCP 调用成功。

若报“缺少刷新令牌”,首先检查 Expire user authorization tokens 与客户端类型,再重新从 EasyXAI 授权。GitHub 最新官方文档也提供了 OAuth App 的可过期令牌机制;本页沿用项目既有的 GitHub App 接入方式,不能把“普通 OAuth App 永远不支持刷新”当作判断依据。详见排查说明。