Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

7.1 KB
Raw Blame

GitHub 登录与仓库授权统一方案

状态:设计建议,尚未修改登录和账号创建逻辑。

用户流程

登录页提供「使用 GitHub 继续」作为推荐入口,账号密码作为其他登录方式保留。首次 GitHub 登录时,在部署允许注册的前提下自动建立平台账号;已有绑定的用户直接进入工作台。用户无需单独填写用户名、密码和确认密码。

登录完成后可以立即体验不需要代码仓库的功能。用户添加仓库时,再按需连接 GitHub 仓库并选择仓库。不要为了进入平台,强制要求用户授予私有仓库读写权限。

已有密码账号的用户先通过原方式登录,再明确选择「绑定 GitHub 登录」。绑定后仍保留原有项目、历史运行、权限和凭据。

登录与代码访问的边界

用途 结果 凭据处理
登录平台 解析 GitHub 用户身份,建立或查找平台账号,签发平台自己的会话 Cookie 不把仅用于登录的令牌写入 GitToken,不覆盖已有仓库凭据
绑定登录方式 在当前已登录且重新验证过的用户与 GitHub 身份间建立关联 必须显式确认,不能通过同名或相同邮箱自动合并
连接仓库 在当前用户明确同意后取得代码访问能力,列出可访问仓库 仓库令牌保留在用户凭据域,按实际返回的权限判断可用能力

这两类用途可以使用同一个 GitHub OAuth App,并共享授权客户端、设备码、错误处理等基础设施;账号关联、平台会话、授权目的与令牌存储需要分别处理。不能把「取消仓库授权」解释为删除平台账号,取消平台登录绑定也不应隐式删除仓库凭据。

OAuth 网页跳转与 PIN 的选择

  • 固定域名的平台优先使用网页 OAuth:点击按钮、在 GitHub 同意、回到平台。注册无需另一个表单。服务端配置 Client ID、Client Secret、受信任回调地址,并校验 state、PKCE、浏览器发起状态和授权用途。
  • 自部署实例可提供 PIN 登录:无需为任意用户域名配置网页回调,也无需分发 Client Secret;复用当前设备码授权能力。
  • PIN 需要显示、复制和输入设备码,不等于免输码的一键网页登录。文案应明确「使用设备码登录」,避免承诺与实际操作不一致。
  • 同一个固定网页回调不能直接覆盖所有自部署域名。若未来提供统一登录中转服务,需要单独设计实例注册、受信任跳转和会话交付,不在当前本地授权方案中隐含引入。
  • 当前仓库连接已内置维护方注册的 LoopForge 应用公开 Client ID,不要求用户自行创建应用;这不代表本文提议的 GitHub 注册和登录已经实现。不得借用其他工具的 Client ID 或让用户填写 PAT 作为登录前置条件。

当前代码需要调整的地方

  1. internal/httpapi/github_auth.go 当前要求已登录,并将授权结果直接保存到该用户的 GitToken。该流程是仓库连接,不能直接当成注册入口。
  2. 现有待授权记录以平台 user ID 为键。匿名登录必须绑定独立、短期、不可预测的浏览器发起状态,不能让所有匿名用户共用 user ID 0,也不能只凭浏览器提交的 GitHub 用户名或 flow ID 建立平台会话。
  3. internal/httpapi/auth_tokens.go 需要明确放行 GitHub 登录能力查询、登录开始和回调/轮询端点;这些端点自行验证来源、会话状态和授权目的。仓库连接仍要求已登录,不能整体放开认证相关 API。
  4. 在 UsersRepo 增加持久化外部身份映射,以 provider 与 GitHub 返回的数字 user ID 标识身份,并建立唯一约束。GitHub login、显示名和邮箱都不能作为自动关联已有账号的依据。Github 改名后也不能生成重复平台账号。
  5. authSetup 和 authRegister 目前只看 LocalAccountCount()。直接新增 GitHub 注册会导致已有 GitHub 账号时仍被判断为首次部署,后续密码注册可能错误取得管理员。应统一初始化状态和首位管理员判定,并保证跨登录方式、跨 API 实例并发时只产生一名初始化管理员。
  6. GitHub 自动建号必须服从现有注册开关。关闭注册时,已绑定账号仍可登录;未知身份不能自动加入实例。GitHub 身份验证成功不等于获得该部署的访问权限。
  7. 沿用平台现有用户 ID、项目归属、权限与签名 Cookie。后续 GitHub 登录不重新创建账号,不重置角色,不覆盖其他执行器凭据。用户名冲突应明确处理,不能静默接管同名本地账号。
  8. 登录授权与仓库令牌刷新分别处理。仓库令牌撤销或过期时显示「重新连接仓库」,不应让平台账号和本地密码一起失效。解除最后一种可用登录方式前要求设置替代登录方式。

新增模型遵循 UsersRepo 领域归属;只使用现有增量建表机制或显式 SQL,不增加启动时的数据迁移和 seed。

界面安排

  • 登录页:有可用 GitHub 配置时显示推荐按钮;未配置时保留密码入口,明确说明管理员尚未启用 GitHub 登录。不要出现点击后才报 503 的主按钮。
  • 配置具备网页回调时使用网页 OAuth;只有设备码配置时展示设备码流程和清楚的操作说明。
  • 首次登录:不强制配置模型 Key 或仓库,先给出免 Key 示例和可选的下一步。
  • 个人配置:分别显示「GitHub 登录已绑定」与「GitHub 仓库已连接」,说明切换/解绑影响。
  • 仓库选择:未连接时提供授权入口;已具备所需仓库权限时直接选择仓库,避免无意义的重复授权。GitHub 仓库选择只决定项目绑定,不代表缩小 OAuth repo 授权范围。

验收重点

  • 全新 GitHub 身份完成注册和登录;同一身份重复登录仍是同一用户;GitHub 改名不改变平台用户 ID。
  • 同名本地账号不会被合并或接管;从本地账号绑定已归属其他用户的 GitHub 身份时明确拒绝。
  • 登录授权不会把低权限令牌写入 GitToken 或覆盖现有仓库授权。
  • 多个匿名浏览器、多个标签页、回调重放、用户拒绝、超时和服务重启均有确定结果。
  • 关闭注册后未知 GitHub 身份无法自动注册;已有绑定用户正常登录。
  • 密码注册与 GitHub 注册同时发生时,首次管理员判定正确;Github-only 部署不再显示首次密码初始化。
  • 网页 OAuth 与设备码使用同一身份映射;仓库授权使用明确不同的授权目的。
  • 真实 Client ID 配置后,分别验证真实网页登录、真实 PIN 登录和真实仓库选择;未配置时不声称已完成真实验收。

官方参考