第16章 连接 GitHub

连接 GitHub

Omnigent 支持按用户连接 GitHub。只需服务器管理员配置好 GitHub App，登录用户即可在 设置 → 沙箱集成 → 连接 GitHub 中进行关联。随后，受管沙箱便能以该用户身份认证 git 和 gh——包括克隆私有仓库、推送分支、创建 Pull Request——系统通过短效的按用户令牌实现，而非共享的个人访问令牌。

只有配置了 Credential Store（凭据存储，即 OMNIGENT_CREDENTIAL_* / KMS），此功能才会生效。令牌由凭据存储加密持久化保存；若未配置，连接 GitHub 将记录警告日志并保持禁用状态。

工作原理

连接（用户 OAuth）。服务器生成短效的用户绑定 state，将用户重定向至 GitHub 的授权页面。GitHub 随后重定向回 …/v1/connections/github/callback，该端点将授权码换取用户到服务器的访问令牌（及刷新令牌），并在凭据存储中加密保存。

使用（沙箱内）。沙箱启动时，服务器向 runner 发放该用户的最新令牌，runner 生成 git / gh 凭据并注入用户的公钥 SSH 密钥。刷新令牌可维持长会话的认证状态。

使用 GitHub App，而非 OAuth App 或 PAT。GitHub App 是可由组织拥有、最小权限的身份标识。访问单仓库内容需先将 App 安装到拥有该仓库的账户或组织。这样访问权限可按安装维度审计和撤销，无需泄露长期有效的个人密钥。

核心限制：仅用户 OAuth 能列出用户可见的仓库，但读取私有仓库内容或分支，需要 App 已安装在该仓库的所属账户上。若 App 已连接但未安装，访问私有仓库内容将返回 404。

注册 GitHub App

在 设置 → 开发者设置 → GitHub Apps → 新建 GitHub App（个人版：https://github.com/settings/apps/new；组织版：https://github.com/organizations//settings/apps/new）下注册新 App。

名称 / 主页 URL。任意唯一名称（如 omnigent-connect），主页设置为你 Omnigent 的 origin。 回调 URL。设置为 https:///v1/connections/github/callback。此值须与 OMNIGENT_GITHUB_APP_REDIRECT_URI 一致（若未显式设置，Omnigent 将根据 OMNIGENT_DOMAIN 派生出同构 URL）。 用户授权令牌过期。保持勾选——Omnigent 依赖刷新令牌维持长会话。 安装时请求用户授权 (OAuth) 以及 启用设备流程。两者均不勾选。 Webhook。Omnigent 不消费 webhook，取消“激活”勾选，URL 留空。 权限。在 仓库权限 下仅授予沙箱所需权限。用户到服务器令牌将继承这些权限范围，此列表即沙箱以该用户身份操作的上限。

权限 访问范围 说明 Contents 读写 克隆仓库并为 PR 推送分支。若沙箱仅克隆，可设只读。 Metadata 只读 自动选中；GitHub 强制要求。 Pull requests 读写 沙箱内创建 PR。若从不创建 PR，可设只读。

其余权限均设为 无访问。无需账户或组织级权限。

App 可安装的位置？单账户或开发实例选 仅本账户；若其他组织也将安装，选 任意账户。点击 创建 GitHub App。

收集凭据

在 App 的 常规 页面获取：

Client ID — 非敏感，对应 OMNIGENT_GITHUB_APP_CLIENT_ID。 Client secret — 点击 生成新的客户端密钥 并复制（GitHub 仅显示一次），对应 OMNIGENT_GITHUB_APP_CLIENT_SECRET。 App ID（可选）— 顶部的数字 ID，对应 OMNIGENT_GITHUB_APP_ID。仅用于 App 级 JWT 调用，按用户连接流程不需要。 Private key（可选）— 生成私钥 下载 .pem 文件。仅用于 App 级（安装令牌）调用。对应 OMNIGENT_GITHUB_APP_PRIVATE_KEY（PEM 内容）或 OMNIGENT_GITHUB_APP_PRIVATE_KEY_PATH（文件路径）。

务必将 client secret 和 private key 视为密码——绝不提交到代码库；应存放到服务器已读取的密钥存储中。

安装 App

打开 App 的 安装应用 选项卡（或 https://github.com/apps//installations/new），将其安装到用户将访问仓库的账户或组织，并选择 所有仓库 或特定仓库集。此步骤对私有仓库内容必不可少：若 App 未安装在仓库所有者处，即使连接成功，克隆或列出私有仓库分支仍会返回 404。

设置 OMNIGENT_GITHUB_APP_SLUG 为 App 的 slug（取自 URL 中 github.com/apps/），供产品内“安装”链接使用。

配置服务器

设置以下变量。只要存在 client id、client secret 及可解析的 redirect URI，且凭据存储已配置，功能即自动启用：

``` # 必需。 OMNIGENT_GITHUB_APP_CLIENT_ID=Iv23li... # App “Client ID” OMNIGENT_GITHUB_APP_CLIENT_SECRET= # 来自“生成新的客户端密钥”

# Redirect URI — 显式设置，或留空让 Omnigent 从 OMNIGENT_DOMAIN 派生 # 为 https://$OMNIGENT_DOMAIN/v1/connections/github/callback（同构）。 OMNIGENT_GITHUB_APP_REDIRECT_URI=https:///v1/connections/github/callback

# 可选。 OMNIGENT_GITHUB_APP_SLUG=omnigent-connect # 用于产品内安装链接 OMNIGENT_GITHUB_APP_ID=1234567 # 仅用于 App 级 JWT 调用 OMNIGENT_GITHUB_APP_PRIVATE_KEY_PATH=/etc/omnigent/github-app.pem # 或 _PRIVATE_KEY= ```

变量 是否必需 用途 OMNIGENT_GITHUB_APP_CLIENT_ID 是 用户授权流程的 App 客户端 ID。 OMNIGENT_GITHUB_APP_CLIENT_SECRET 是 App 客户端密钥。 OMNIGENT_GITHUB_APP_REDIRECT_URI 是* OAuth 回调 URL。*若未设置，将从 OMNIGENT_DOMAIN 派生。 OMNIGENT_GITHUB_APP_SLUG 否 App slug，用于构建产品内安装链接。 OMNIGENT_GITHUB_APP_ID 否 App 数字 ID，仅用于 App 级 JWT 调用。 OMNIGENT_GITHUB_APP_PRIVATE_KEY 否 RSA 私钥 PEM 内容，用于 App 级调用。 OMNIGENT_GITHUB_APP_PRIVATE_KEY_PATH 否 私钥 PEM 文件路径（替代内联值）。

重启服务器。若已设置 client id 和 secret 但无法解析 redirect URI（OMNIGENT_GITHUB_APP_REDIRECT_URI 和 OMNIGENT_DOMAIN 均未设），功能将记录警告并禁用。CLI（omnigent server）和 Docker 镜像读取相同的环境变量。

验证

以真实用户身份登录 Omnigent，打开 设置 → 沙箱集成。若连接 provider 已配置（/v1/info 中 enabled_connections 包含该项），将显示 连接 GitHub 控件。

点击 连接 GitHub，在 GitHub 授权页面完成授权，返回 Omnigent。面板将显示 已连接为 。断开连接会撤销存储的令牌。

在 App 已安装的账户拥有的私有仓库上启动沙箱会话，确认沙箱可执行 git clone、推送分支，并在启用时创建 Pull Request。

若第 3 步对私有仓库返回 404 且连接流程成功，说明 App 已连接但未安装在该仓库所有者处——请重新执行 安装 App。