阅读导览
XHGit 提供访问令牌、API、Webhook、第三方登录和 OAuth 应用。它们分别用于程序调用、事件通知和身份授权,权限与回调地址不能混用。本页只使用测试占位值;接入时应先在测试仓库完成验证,再用于真实自动化。
创建用途单一的访问令牌
- 登录后进入应用设置,创建访问令牌并填写便于识别的名称。
- 按业务选择范围:读取仓库、写入仓库、读取或写入软件包等;按页面提供的选项限定仓库访问范围。
- 生成后保存在密码管理器或自动化 Secrets,记录使用位置与责任人。
- 任务结束或凭据泄漏时撤销令牌,使用新令牌更新调用方。
令牌不能提升账号本来没有的权限,公开资源限制或特定仓库范围也会继续生效。网页账号密码、短信验证码、Runner 注册令牌与个人访问令牌用途不同,不能互相代替。
调用 API 并检查结果
通用 API 使用 /api/v1,软件包使用 /api/packages,不是同一个路径前缀。示例读取公开仓库信息:
curl --fail https://git.example.test/api/v1/repos/team/demo
需要认证时,通过受保护的调用配置传入 Authorization: token TEST_TOKEN,其中 TEST_TOKEN 仅是占位符,真实值不要出现在仓库和日志中。程序应检查 HTTP 状态、解析错误体并处理分页,不能只凭收到了 JSON 就认定操作成功。写入操作前确认资源归属、请求方法和数据范围。
用 Webhook 接收仓库事件
- 仓库管理员进入“设置 → Webhook”,添加当前支持的接收类型。
- 填写自己控制的接收地址、密钥和所需事件,避免订阅不必要的数据。
- 保存后发送测试事件,在递送记录中查看时间、请求与响应结果。
- 接收服务按对应签名规则验证请求,限制重复处理,并返回能代表处理结果的状态。
Webhook 是事件通知,不会自动给接收方仓库访问权限,也不能当作持久任务队列。接收地址不可达、签名不匹配或返回非成功状态时,先检查递送详情,再按界面支持的方式重放。递送内容可能包含私有仓库信息,记录只向需要的管理员开放。
将 GitHub 关联到已有账号
先登录自己的 XHGit 账号,在安全设置的关联账号区域选择已启用的 GitHub 登录源,再到 GitHub 完成授权。返回后核对关联列表;新用户从登录流程进入时,应按页面选择登录已有账号或注册,避免形成两个独立账号。
管理员配置外部登录应用时,回调通常形如 https://git.example.test/user/oauth2/github/callback。这里 github 必须是实际登录源名称,协议、域名、端口、站点子路径和回调路径必须与双方配置一致。redirect_uri 不匹配时,不要反复修改个人密码;应核对应用、ROOT_URL 与反向代理实际对外地址。
让其他应用使用 XHGit 登录
这与“使用 GitHub 登录 XHGit”方向相反。在个人或组织的应用设置中注册 OAuth2 应用,填写准确的重定向 URI,按应用性质选择适用的客户端方式,再在自己的应用中保存客户端配置。
授权入口为 /login/oauth/authorize,令牌入口为 /login/oauth/access_token。回调 URI 应为自己应用真实接收授权结果的地址,不能填登录首页。客户端秘密保存在服务端,公共客户端按所需流程使用安全参数;用户授权时只申请实际必要的范围。失效、撤销与更新凭据都需要调用方正确处理。
把自动化凭据留在安全位置
诊断授权与通知问题
401 先查凭据是否有效和请求认证方式;403 查范围及账号权限;404 同时检查资源名称、路径与隐私权限;回调失败检查两端地址;Webhook 失败查看递送响应。向维护者提供脱敏请求、响应状态和发生时间即可,不需要发送完整认证头。邮件通知失败时,先核对邮箱激活与通知订阅,再联系站点支持。