XHGit · 产品文档

API、Webhook 与应用

访问令牌、第三方登录、OAuth 应用、Webhook 和自动化连接。

01

阅读导览

XHGit 提供访问令牌、API、Webhook、第三方登录和 OAuth 应用。它们分别用于程序调用、事件通知和身份授权,权限与回调地址不能混用。本页只使用测试占位值;接入时应先在测试仓库完成验证,再用于真实自动化。

02

创建用途单一的访问令牌

  1. 登录后进入应用设置,创建访问令牌并填写便于识别的名称。
  2. 按业务选择范围:读取仓库、写入仓库、读取或写入软件包等;按页面提供的选项限定仓库访问范围。
  3. 生成后保存在密码管理器或自动化 Secrets,记录使用位置与责任人。
  4. 任务结束或凭据泄漏时撤销令牌,使用新令牌更新调用方。

令牌不能提升账号本来没有的权限,公开资源限制或特定仓库范围也会继续生效。网页账号密码、短信验证码、Runner 注册令牌与个人访问令牌用途不同,不能互相代替。

03

调用 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 就认定操作成功。写入操作前确认资源归属、请求方法和数据范围。

04

用 Webhook 接收仓库事件

  1. 仓库管理员进入“设置 → Webhook”,添加当前支持的接收类型。
  2. 填写自己控制的接收地址、密钥和所需事件,避免订阅不必要的数据。
  3. 保存后发送测试事件,在递送记录中查看时间、请求与响应结果。
  4. 接收服务按对应签名规则验证请求,限制重复处理,并返回能代表处理结果的状态。

Webhook 是事件通知,不会自动给接收方仓库访问权限,也不能当作持久任务队列。接收地址不可达、签名不匹配或返回非成功状态时,先检查递送详情,再按界面支持的方式重放。递送内容可能包含私有仓库信息,记录只向需要的管理员开放。

05

将 GitHub 关联到已有账号

先登录自己的 XHGit 账号,在安全设置的关联账号区域选择已启用的 GitHub 登录源,再到 GitHub 完成授权。返回后核对关联列表;新用户从登录流程进入时,应按页面选择登录已有账号或注册,避免形成两个独立账号。

管理员配置外部登录应用时,回调通常形如 https://git.example.test/user/oauth2/github/callback。这里 github 必须是实际登录源名称,协议、域名、端口、站点子路径和回调路径必须与双方配置一致。redirect_uri 不匹配时,不要反复修改个人密码;应核对应用、ROOT_URL 与反向代理实际对外地址。

06

让其他应用使用 XHGit 登录

这与“使用 GitHub 登录 XHGit”方向相反。在个人或组织的应用设置中注册 OAuth2 应用,填写准确的重定向 URI,按应用性质选择适用的客户端方式,再在自己的应用中保存客户端配置。

授权入口为 /login/oauth/authorize,令牌入口为 /login/oauth/access_token。回调 URI 应为自己应用真实接收授权结果的地址,不能填登录首页。客户端秘密保存在服务端,公共客户端按所需流程使用安全参数;用户授权时只申请实际必要的范围。失效、撤销与更新凭据都需要调用方正确处理。

07

把自动化凭据留在安全位置

仓库、用户或组织当前启用的 Actions 设置可管理 Secrets 和变量。秘密用于令牌、签名和密码,变量用于普通配置。工作流引用秘密不等于运行代码可信,应同时审查工作流改动和 Runner 的权限范围。

部署密钥在仓库“设置 → 部署密钥”管理,通常用于机器读取指定仓库;是否允许写入要按实际需要配置。不要为下载一个仓库而共享管理员个人凭据。自动打包与构建环境分别见多平台打包和Runner。

08

诊断授权与通知问题

401 先查凭据是否有效和请求认证方式;403 查范围及账号权限;404 同时检查资源名称、路径与隐私权限;回调失败检查两端地址;Webhook 失败查看递送响应。向维护者提供脱敏请求、响应状态和发生时间即可,不需要发送完整认证头。邮件通知失败时,先核对邮箱激活与通知订阅,再联系站点支持。