GitHub App 无状态安装令牌完成上线意味着什么

GitHub App 无状态安装令牌已经完成分阶段上线。对大多数调用方来说，API 用法、权限模型和过期策略都没有改变；真正需要排查的是“令牌长什么样”这件事。新令牌仍以 ghs_ 开头，但长度从过去约 40 个字符变成约 520 个字符。只要系统把令牌当作不透明字符串，而不是按固定格式解析，这次变化通常不需要改业务逻辑。

官方地址：https://github.com/

官方变更说明：https://github.blog/changelog/2026-10-02-stateless-github-app-installation-tokens-rolled-out/

先看清这次上线到底改变了什么

GitHub 公告把这次变化分成两个层次：令牌发行与校验采用无状态格式，令牌外观因此变长；调用方获得的能力边界仍由 GitHub App 的安装权限决定。创建安装令牌时，仍然可以通过 repositories 或 repository_ids 缩小仓库范围，也可以通过 permissions 缩小权限。没有额外指定时，令牌仍继承应用已获授的范围。

旧系统最值得先查的四个位置

第一处是校验器。代码里如果出现“长度必须等于 40”、只允许某个旧正则，或者把令牌按分段字段解析，应该改成非空字符串与必要的前缀检查。更稳妥的边界是：应用负责保存和转发，GitHub 负责解释令牌。

第二处是存储链路。数据库列、密钥管理系统、环境变量加载器和配置中心都可能设置较小的最大长度。不要只看业务表结构，还要检查序列化、审计事件和缓存键值的限制。

第三处是网络链路。反向代理、API 网关或自定义中间件如果对 Authorization 头设置了异常严格的上限，可能出现“生成成功、转发失败”的假象。测试时应让长令牌走完整链路，并记录状态码和请求链路，而不是把令牌本身写进日志。

第四处是脱敏和观测。旧规则可能只遮蔽固定长度的 ghs_ 字符串，导致长令牌在错误日志、请求追踪或调试事件中露出。脱敏应按字段语义处理整个机密值，日志只保留长度、前缀或不可逆摘要。

// 令牌只作为不透明字符串传递，不尝试解码其中的字段。
func buildAuthHeader(token string) (string, error) {
    // 空令牌直接拒绝，避免把错误请求送到 GitHub。
    if token == "" {
        return "", errors.New("installation token is empty")
    }
    // 不记录 token 内容；长度只能用于排查，不可作为权限判断。
    return "Bearer " + token, nil
}

用临时开关做一次可控的双格式灰度

GitHub 提供了临时的 X-GitHub-Stateless-S2S-Token 请求头，方便应用按需验证新格式。它适合测试环境或受控灰度：先让旧格式和新格式分别经过生成、存储、代理和 API 调用，再对比成功率、401/4xx、网关拒绝和日志脱敏结果。

这个请求头不是业务鉴权方式，也不是长期兼容层。公告说明它将在 2026 年 11 月 30 日弃用；完成双格式验证后，应从生产代码和配置中删除。若测试只在应用进程内拼接 Authorization，而没有覆盖外部网关，仍可能遗漏截断问题。

1. 在测试环境生成一枚新的安装令牌，记录过期时间、权限和仓库范围，不记录完整值。
2. 让它经过真实的密钥存储、缓存、代理和 GitHub API 调用链路。
3. 分别观察正常响应、令牌过期后的 401，以及日志和追踪系统中的脱敏结果。
4. 把固定长度断言改为不透明字符串处理，再移除临时请求头并重新回归。

迁移结论：改“假设”，不要改权限模型

这次上线并不要求把安装令牌当成可解析的 JWT，也不意味着可以延长令牌寿命或绕过权限配置。应用仍应缓存有效令牌，接近过期或收到 401 时重新申请；创建令牌时继续显式收窄仓库和权限范围。真正的改动是删除长度、字符模式和中间件容量上的旧假设。

如果系统已经使用 Octokit 等 SDK，优先确认 SDK 与外围存储、网关、日志平台的兼容性。SDK 可以负责令牌申请和过期重建，但无法替你修复数据库列过短、代理头部限制或错误上报泄露问题。

常见问题

新安装令牌还能用原来的 REST API 吗？

可以。官方说明安装令牌 REST API 端点没有改变，权限与仓库范围规则也没有改变。

看到 ghs_ 前缀就能判断令牌有效吗？

不能。前缀只能帮助识别大类，不能替代服务端校验，也不能证明令牌未过期或拥有某项权限。

要不要把数据库字段改成 520 个字符？

应先检查实际字段、序列化层和密钥服务的容量。不要把“约 520”当成新的永久协议，设计上应允许不透明机密值有更大的可用长度。

临时请求头应该一直保留吗？

不应该。它用于按需验证新格式，完成双格式测试后应在 2026 年 11 月 30 日前从生产配置移除。