GitHub App 安装令牌变长后怎样排查集成兼容性

GitHub App 安装令牌的兼容性问题，重点不在重新申请权限，而在于旧系统是否把令牌误当成了“固定长度的字符串”。GitHub 官方已完成 stateless installation token 的分阶段发布：新签发令牌仍以 ghs_ 开头，但长度从约 40 个字符变为约 520 个字符；权限、仓库范围、1 小时有效期和安装令牌接口没有改变。

官方地址：https://github.blog/changelog/2026-10-02-stateless-github-app-installation-tokens-rolled-out/

排查时先把安装令牌恢复成不透明字符串：删除固定 40 字符校验，检查存储和 Authorization 转发容量，再修正日志脱敏规则。不要用“看起来像旧令牌”作为业务判断。

这次变化到底改了什么

以前的集成代码常把令牌长度写进校验器、数据库字段或正则表达式里。新格式的长度变化会暴露这些隐含假设，但不会改变调用方应遵守的权限模型。可以把影响拆成两组：

先删除“固定长度令牌”的代码假设

第一处检查通常是校验器。类似 len(token) == 40、只允许旧格式的正则，或把令牌切片后再比较的逻辑，都不应该继续承担合法性判断。应用侧只需要确认令牌非空，并把真正的有效性判断交给 GitHub API。

// 令牌是凭据，不按长度或内部字符推断权限。
func addGitHubAuth(req *http.Request, installationToken string) error {
    if strings.TrimSpace(installationToken) == "" {
        return errors.New("installation token is empty") // 空值属于本地配置错误
    }
    // Authorization 头完整透传，避免切片或拼接破坏长令牌。
    req.Header.Set("Authorization", "Bearer "+installationToken)
    req.Header.Set("Accept", "application/vnd.github+json")
    return nil
}

这个片段只说明调用方的边界，不代表本地运行结果。真正需要确认的是：中间层不会重新格式化令牌，失败响应仍会被记录为 GitHub API 返回的认证错误，而不是被本地长度校验提前拦截。

按四层链路排查“变长后请求失败”

如果升级后突然出现认证失败，可以沿着令牌的生命周期检查，不要只盯着申请令牌的代码。

1. 校验层：搜索 40、长度上限、旧版正则和“只允许某种前缀”的业务判断。前缀可以作为格式观察，但不能代替 API 鉴权。
2. 存储层：检查数据库字段、密钥服务、配置中心和环境变量注入是否存在过小的长度上限。尤其关注会自动截断的字段或密钥同步组件。
3. 传输层：检查反向代理、API 网关和 HTTP 中间件是否拒绝较长的 Authorization 头，或者在重试、转发时只保留固定长度。
4. 日志层：脱敏规则不能只匹配旧令牌模式。记录请求诊断信息时保留状态码、请求阶段和关联 ID，不记录令牌正文。

把临时兼容开关当成退出项管理

GitHub 公告说明，临时的 X-GitHub-Stateless-S2S-Token 请求头将在 2026 年 11 月 30 日后不再被尊重。它适合用来验证双格式兼容，不适合成为长期业务依赖。建议建立一张迁移清单：

• 在测试环境同时覆盖旧格式和新格式，重点观察存储、代理和脱敏链路。
• 把令牌字段设计为可容纳未来变化的字符串，而不是绑定当前长度。
• 确认所有调用方使用完整 Authorization 值，不在日志、指标标签或错误消息中输出凭据。
• 验证完成后删除临时请求头和相关分支，并保留一次变更记录。

常见问题

令牌变长后需要重新申请 GitHub App 权限吗？

不需要因为长度变化重新设计权限。官方说明权限、仓库范围和有效期保持不变；如果请求失败，应优先排查本地长度假设、存储容量和 HTTP 转发链路。

能不能继续用正则判断它是不是 GitHub App 令牌？

正则可以用于诊断输入来源，但不应作为令牌有效性或权限的最终判断，更不能假设固定字符数。应用应安全保存并完整透传令牌，再根据 GitHub API 的响应处理认证结果。

这次变更的核心动作很明确：把令牌从“有固定形状的业务字段”还原成“不透明凭据”，并逐层移除长度、截断和旧格式脱敏带来的隐性约束。