Token Permissions

Token 权限

TriForge 需要 Token 同时完成平台 API 操作和匹配实例的 HTTPS Git 操作。权限不足时可能出现“连接验证成功，但搜索、创建仓库或 Push 失败”，因为 /user 只证明身份有效，不证明所有后续权限都已授予。

权限名称会随托管平台版本和管理员策略变化。优先遵循实例自己的 Token 页面与官方文档；只授予完成工作所需的最小权限，并设置合理到期时间。

TriForge 会做哪些远程操作

功能	所需能力
验证连接	读取当前用户身份
搜索/列出仓库	读取当前账号可访问的仓库元数据
克隆/Fetch/Pull	读取目标仓库内容
创建缺失仓库	在当前个人命名空间创建公开或私有仓库
同步 Push	写入目标仓库 Git 内容和分支

0.5.0 自动创建的是当前用户个人命名空间仓库，不提供组织/群组命名空间选择器。

GitHub

Classic Personal Access Token

最直接的选择通常是：

• 私有仓库读写与创建：repo；
• 只创建/操作公开仓库时，部分场景可用 public_repo，但同步到私有仓库仍需要 repo。

如果组织启用了 SAML SSO，创建 Token 后还可能需要在 GitHub 中对该组织授权 Token。

Fine-grained Personal Access Token

建议按需要限制：

• Resource owner：选择自己的账号；
• Repository access：选择允许访问的仓库；
• Metadata：读取；
• Contents：读写，用于 HTTPS Git 读写；
• Administration：写入，GitHub“为当前认证用户创建仓库”API要求该仓库权限。

Fine-grained Token 的组织策略、待审批状态和仓库选择范围都可能限制操作。一个只授权“现有仓库”的 Token 无法凭空访问未在范围内的新仓库时，应根据 GitHub 页面提示调整授权或改用符合团队策略的方式。

官方参考：

• GitHub REST：为当前用户创建仓库
• GitHub：Fine-grained PAT 权限表

GitLab

推荐使用 Personal Access Token，并授予：

• api：TriForge 需要读取用户/项目、搜索以及创建项目的完整 API 读写能力；
• write_repository/read_repository 在某些受限设计中覆盖 Git over HTTPS，但单独使用它们不足以完成创建项目 API；因此完整工作流仍推荐 api。

GitLab 新建 Token 通常必须设置到期日。管理员还可能限制最长有效期、禁用个人 Token，或启用额外身份策略。

官方参考：GitLab Personal Access Tokens。

GitLab DPoP 注意事项

如果实例为 PAT API 请求强制启用了 DPoP，普通 PRIVATE-TOKEN 请求还需要动态签名头。TriForge 0.5.0 不生成 DPoP，因此这种策略下 API 连接会失败；请让管理员提供兼容方式，或等待扩展显式支持。不要关闭 TLS 校验规避认证策略。

Gitea

不同 Gitea 版本的 Token UI 和 scope 模型差异较大。支持细粒度 scope 的版本至少需要：

• read:user：验证当前账号；
• write:repository：搜索/读取、创建仓库和 Git 内容读写；write 通常包含相应 read。

有的旧版实例只提供较粗粒度 Token，或使用 all。不要因为文档示例存在 all 就默认授予所有权限；先尝试仓库与用户所需的最小权限。

官方参考：Gitea API Usage。

Token 生命周期建议

• 为 TriForge 单独创建 Token，名称中注明设备，例如 TriForge-MacBook。
• 设置合理的到期日期，并在密码管理器中记录到期提醒。
• 不在多个不受控设备之间共用长期 Token。
• 离职、设备丢失或怀疑泄漏时，先在平台撤销 Token，再删除 TriForge 连接。
• 定期查看平台 Token 的最后使用时间和来源 IP（平台支持时）。
• 不把 Token 写入 .env、settings.json、Git URL、Wiki 或 Issue。

更换 Token

1. 在平台创建新 Token 并验证权限。
2. TriForge“托管平台” → 选择连接 → “修改”。
3. 保持实例 URL 不变，在第 3 步输入新 Token。
4. 等待身份验证成功。
5. 回到平台撤销旧 Token。

先验证新 Token 再撤销旧 Token，可以减少中断；但怀疑泄漏时应立刻撤销旧 Token。

常见权限症状

症状	常见原因
能连接，搜索不到私有仓库	Token 未授予私有仓库读取，或仓库不在 fine-grained 选择范围
能搜索，无法创建仓库	缺少 API/Administration 写权限，或实例管理员禁止用户建库
能创建仓库，Push 403	缺少仓库内容写入权限、分支保护或组织策略拒绝
Push 404	平台为隐藏无权限资源返回 404，或 namespace/仓库名不匹配
Token 突然失效	到期、被撤销、SSO 授权失效、管理员策略变化

进一步排查见 故障排查。