GitHub App 设置
Themis 通过一个名为 Themis AI Agent 的 GitHub App 向 GitHub 认证。一次应用注册即可覆盖部署中的所有 Space；每个 Space 都安装同一个应用，并获得自己的 installation_id。
为什么使用 GitHub App（而不是 PAT）
- 私有组织中无需专用的 Bot 席位。
- 按安装计费的速率限制（每个安装每小时 5k 次，而非每个 Bot 账号）。
- 细粒度的仓库权限；组织管理员只需为整个团队安装一次。
- Webhook 投递与应用捆绑，无需按仓库逐个配置。
注册应用
每次部署在你的 GitHub 用户或组织下注册一次应用。前往 https://github.com/settings/apps/new。
基本信息
- Name：
Themis AI Agent - Homepage URL：你的部署 URL（例如
https://3coms.dev） - Where can this GitHub App be installed：Any account
识别和授权用户
- Callback URL：
https://<your-deployment>/github_app/oauth/callback - ☑️ Request user authorization (OAuth) during installation
- ☑️ Expire user authorization tokens
- ☐ Enable Device Flow
安装后
- Setup URL：留空（启用安装期间 OAuth 时会被禁用）
- ☑️ Redirect on update
Webhook
- ☑️ Active
- URL：
https://<your-deployment>/webhooks/github - Secret：生成一个随机的十六进制字符串——你会把它保存到 Rails credentials 中
仓库权限
| 权限 | 级别 | 原因 |
|---|---|---|
| Contents | Read & write | 代码生成提交 |
| Pull requests | Read & write | 审查、内联评论、创建 PR |
| Issues | Read & write | Sentry → issue、评论 |
| Checks | Read | CI 状态 |
| Commit statuses | Read | 旧版 CI 状态 |
| Actions | Read | 工作流运行结果 |
| Workflows | Read & write | 推送 .github/workflows/* 变更 |
| Metadata | Read | 自动授予 |
组织权限
| 权限 | 级别 |
|---|---|
| Members | Read |
账户权限（user-to-server OAuth）
| 权限 | 级别 |
|---|---|
| Email addresses | Read |
订阅事件
Pull request、Pull request review、Pull request review comment、Issue comment、Issues、Push、Check run、Check suite、Workflow run、Release、Installation target。
创建应用后，在应用设置页面生成一个私钥并下载 .pem 文件。
保存凭据
添加到你加密的 credentials 中：
bin/rails credentials:edit --environment=production
github_app:
app_id: <应用页面的整数>
client_id: <应用页面的字符串>
client_secret: <应用页面的字符串>
webhook_secret: <你在 webhook 上设置的随机十六进制字符串>
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
如果你的 app slug 与默认的 themis-ai-agent 不同（例如你取了别的名字），还需要加上：
github_app:
app_slug: <your-slug>
更新 credentials 后重启 Rails 服务器。
安装到 Space
Space 所有者/经理自助安装：
- 打开 Space Settings → Connections → GitHub。
- 点击 Install GitHub App。
- 在 GitHub 上，选择个人账号或组织。对于组织，管理员一次安装即覆盖所有成员。
- GitHub 会重定向回 Themis —— 安装 ID 会绑定到该 Space。
同一个用户可以拥有独立的”个人”和”工作”Space，每个都有自己的安装。
Webhook 流程
GitHub 会用应用级别的 webhook_secret 为每次投递签名。Themis 验证 HMAC，从 payload 中读取 installation.id，并通过 space_channels 表上唯一的 github_installation_id 列解析 Space。
令牌生命周期
Themis 按需铸造安装访问令牌。令牌有效期为一小时；Themis 缓存 55 分钟并透明地刷新。令牌永远不会落到数据库中——只有安装 ID 会保存。
故障排查
“GitHub App is not configured on this deployment” —— 凭据缺失或格式错误。仔细检查 private_key 的 YAML 缩进（必须使用 | 字面块）。
Webhook 返回 401 —— credentials 中应用级别的 webhook_secret 与你在应用注册时设置的 secret 不匹配。
Webhook 返回 No space bound to installation <id> —— Space 已断开连接，但 GitHub 上仍然安装着应用。请从 Space Settings 重新安装，或在 https://github.com/settings/installations 上从 GitHub 卸载。