GitHub App 令牌变长后报错？旧校验迁移与鉴权排查

这次改变什么，哪些系统需要检查

GitHub 于 2026 年 10 月 2 日宣布默认切换完成：新安装令牌采用 ghs_APPID_JWT 格式，仍以 ghs_ 开头，长度从 40 变为约 520 字符。应作为不透明字符串处理，不能要求固定长度或依赖内部结构；权限、仓库范围和签发接口没有因此改变。

原始适用说明涵盖 GitHub Enterprise Cloud 与 Data Residency，GitHub Enterprise Server 不受这次变更影响。先找到项目实际使用的凭据类型和签发位置；个人访问令牌、应用自身的 JWT 与安装令牌不是同一个对象，不能看到 GitHub 鉴权错误就替换同一套配置。

第一步：区分签发失败和使用失败

官方流程是用 App JWT 请求 POST /app/installations/{installation_id}/access_tokens，取得安装令牌和 expires_at 等响应信息。这个签发请求与之后使用安装令牌调用业务接口，是两个不同阶段。

先在程序中找出报错发生的位置。如果签发请求还没成功，就核对安装 ID、App JWT 和该请求的错误响应；如果已经拿到 token，却在表单验证、保存或后续调用中失败，才沿令牌处理链继续检查。不要把签发用的 JWT 写入本应保存安装令牌的位置，也不要为了排查而把两种凭据复制到日志里。

第二步：找到令牌第一次发生变化的位置

把处理链划成四个位置：解析签发响应之后、准备写入存储之前、从存储读出之后，以及构造 Authorization 之前。在受控排错过程中比较相邻位置的长度和内容是否完全相同，对外只记录位置、长度和相等与否。比较必须针对同一枚令牌，不能把两次签发结果不同误认为传输损坏。

若写入前完整、读出后变短，优先检查字段容量、序列化和保存逻辑；若内容未变化却在发送前被拒绝，定位执行拒绝的校验函数，检查固定长度判断和旧正则。若这些位置一致，而请求在网关处失败，再核对该链路的请求头限制与拒绝日志。这里的现象用于缩小范围，并不能单独证明 GitHub 服务发生故障。

修复后可先用明显标记为测试数据的合成字符串检查同一读写路径，覆盖短值、约 520 字符及更长值，并包含点号、下划线和连字符。检查读回值是否逐字符一致；不要把合成值发给 GitHub，也不要把“接受了合成字符串”当作鉴权成功。这个方法是验证建议，本文没有执行真实账号测试。

第三步：令牌完整时，按响应排查鉴权

REST 文档说明，安装令牌创建一小时后过期，过期使用会返回 401。先对照签发响应的 expires_at，确认是否仍在使用旧缓存，再检查刷新逻辑；变更字符串容量不能解决到期问题。

出现 Resource not accessible by integration 时，官方排错文档指向权限不足，可参考 X-Accepted-GitHub-Permissions 响应头核对接口要求。403 或 429 也可能是限流，需结合错误正文及限流响应头判断；不要直接扩大权限或立即重复请求。

确认令牌完整且未过期后，可在获授权的测试环境用只读 GET /installation/repositories 核对可访问仓库。成功仅说明这一请求可用；随后仍要检查实际业务端点的权限。若请求私有仓库得到 404，也应核对安装所属账号和仓库范围，不急着判断仓库被删除。

临时格式 header 什么时候移除

临时 X-GitHub-Stateless-S2S-Token header 将于 2026 年 11 月 30 日退役，此后不再生效。它作用于安装令牌签发请求；原说明接受 enabled 或 disabled，true、false 等值会被忽略。

在代码中搜索完整 header 名称，并检查配置模板、SDK 封装和部署参数是否还会注入它。不要只删除一个调用处，却让公共客户端继续附加旧值。完成两种格式的兼容验证后移除临时覆盖，再用正常签发路径确认集成；不应把 disabled 当作长期修复方案。

怎样确认修复覆盖了真实处理链

验收应回答三个具体问题：合成值经过保存和读出后是否保持一致；正常签发的令牌能否通过自己的处理链；获授权的最小业务请求能否成功。每一步对应不同原因，不能只看到数据库扩容成功，就认定整个集成已经修好。

最后检查日志脱敏是否也能覆盖新的长值。使用测试字符串验证脱敏结果，不靠输出真实凭据来检查规则。若仍失败，交接错误阶段、状态码、错误正文、长度比较结果和所需权限即可，移除其中的凭据信息；这样下一位维护者可以接着定位，而无需重新接触令牌原文。