GitHub App installation token 格式要变了？先查这 4 处最容易把集成打断的硬编码

Article type: tutorial
Voice: operator

如果你的系统里用到了 GitHub App installation token，这两天最该检查的不是权限范围，而是你有没有把它当成“固定 40 个字符的 ghs_ token”写死在代码里。

短答案先给出来：从 2026-04-27 开始，GitHub 会分阶段把 GitHub App installation token 换成更长、可变长度的新格式；只要你的集成依赖 token 长度、正则、数据库字段宽度，或者会去解析 token 内容，就有机会在 rollout 期间出问题。 对很多团队来说，这不是“认证机制重写”，而是一轮很具体的兼容性体检：先查硬编码，再查存储，再查日志和代理链路。

先把名字说准，避免术语漂移：本文讲的 GitHub App installation token，是 GitHub App 以 installation 身份调用 API 时拿到的访问令牌；GitHub 在 changelog 里也明确写了，后续分阶段 rollout 还会覆盖 GitHub Actions 发出的 GITHUB_TOKEN。它们都属于这轮格式变更的影响面，但 GitHub Enterprise Server（GHES）当前不在这次变更范围内。

快速判断（2026-04-25，基于 GitHub 官方 changelog + Docs）

• 旧的安装令牌常被客户端当成固定长度的 ghs_ 字符串处理。
• 新格式会变成 约 520 字符、且长度可变 的 ghs_APPID_JWT 形态。
• GitHub 明确提醒：不要按长度校验，不要用硬编码正则，不要解析 token 内容。
• 最容易先出问题的不是 GitHub API 本身，而是你自己代码里的校验器、数据库列、日志脱敏规则和代理中间层。

谁应该现在就查，谁可以先不着急

适合马上做这轮检查的人

• 你维护 GitHub App，靠 installation token 调 GitHub REST API 或 GraphQL API
• 你有 GitHub Actions 工作流，且外围代理、审计、凭证中间件会处理 GITHUB_TOKEN
• 你们内部有 token 长度校验、正则白名单、secret masking、数据库落表或缓存层
• 你做的是 CI/CD、代码审查、机器人集成、同步器这类“平时看起来稳定，真出问题会大面积报错”的系统

可以先按较低优先级处理的人

• 你只在浏览器里手工用 GitHub，没写任何 GitHub App 或自动化集成
• 你的系统从头到尾都把 token 当 opaque string，只透传，不校验，不入库，不解析
• 你主要跑的是 GHES，而且确认当前环境不在这次云端 rollout 范围内

这次 GitHub App installation token 变更，真正会打到哪几层

GitHub 这次 changelog 最值得注意的，不是“token 更长了”这句表面信息，而是它同时改了三件事：

1. 长度从固定短串变成约 520 字符、且可变长度
2. 格式从传统 ghs_ 短 token，变成 ghs_APPID_JWT 这种带更多结构信息的新形式
3. GitHub 明确要求客户端把它继续当 opaque string，不要自己验证里面的 JWT 内容

这意味着很多老代码里那些“看起来很合理”的防御式写法，反而会先把你绊倒。真正的风险不是 GitHub 发不出 token，而是你自己的系统先拒收、截断、误判，或者在链路里把它改坏了。

如果你最近关注过 TG Hubs 之前写的 GitHub 把 Copilot CLI 用成个人 command center 后，真正值得抄的不是界面，而是先问清需求再让 agent 动手这条工作流，会发现这是同一种工程判断：越底层、越稳定、越像“不会变”的接口，越不能靠默认想象写死。

先查第一处：长度假设

GitHub 在 changelog 里写得很直接：如果你的应用依赖 installation token 正好 40 个字符，新格式就可能直接把它打断。

这类问题最常见在四个位置：

• len(token) == 40 这类显式校验
• UI 或配置页里给 token 输入框设了长度上限
• SDK 包装层里先做本地合法性判断，再决定是否发请求
• secret 管理表把 token 列宽设得过窄

这也是为什么这篇文章不把角度写成“GitHub token 变长了怎么办”。真正该问的是：你的系统里有没有任何一层，把 GitHub App installation token 当成固定长度凭证。

如果有，这轮兼容性检查就不是“等用户报错再看”，而是应该在 rollout 前自己先扫一遍。

第二处：正则和前缀判断

GitHub 在官方建议里专门点名了这种写法：

ghs_[A-Za-z0-9]{36}

问题不只是这个正则不再匹配，而是很多团队会在它周围再套一层逻辑，例如：

• 匹配不上就当成非法 token
• 匹配不上就不做 secret masking
• 匹配不上就拒绝写日志、缓存或代理透传
• 匹配不上就不允许进某个内部 API

这里最容易误判的一点是：GitHub 没有取消 ghs_ 前缀，变的是前缀后面的结构和整体长度。 所以如果你只做“前缀存在即可”的非常宽松检查，问题可能不大；但如果你把“ghs_ + 固定 36 位字符”当成准入条件，兼容性风险就很高。

在 开发者工具栏目 里，很多文章反复讲的其实是同一件事：真正容易让工具链翻车的，常常不是核心 API，而是边上那些你以为“写死更安全”的小规则。

第三处：数据库列宽和缓存层

GitHub 这次给出的另一个很实用提醒，是数据库字段至少要能容纳 520 字符。

这句话背后其实不只是数据库问题，还牵出三类常被忽略的地方：

• Redis / KV 里为 token 预设的长度或序列化限制
• 审计表、失败重试队列、任务快照里对 token 的截断逻辑
• 内部工具导出 CSV、后台管理页展示、复制按钮等“边缘功能”

很多团队在主流程里把 token 当 header 透传，反而没事；真正先报错的，是异常处理、调试工具、审计落表这些侧链路。因为这些地方最容易带着“反正 token 不长”的默认假设。

如果你此前看过 GitHub 如何用 eBPF 提前拦住高风险部署：一份更实用的借鉴清单，会发现一个共同点：真正省事故的，不是等主流程炸了再查，而是先把旁路链路里的脆弱点补掉。 这次 token 格式变更，同样更像一轮“边缘层稳定性审计”。

第四处：别自己解析 token 内容

这次变更里最容易让人手痒的一点，是 GitHub 明说新格式里带 JWT。很多工程师看到这里，第一反应会是：

• 那我能不能自己 decode 一下？
• 能不能提前读出 installation、app id、过期时间？
• 能不能把它当一种更聪明的本地校验机制？

GitHub 官方答案其实已经给了：不要。

原因很简单：这个 JWT 是 GitHub 内部 issuer 签的，客户端既不该验证，也不该对里面的结构做依赖。只要你把它当成“可解析，所以可以依赖”的对象，后面就等于又给自己埋了一层未来兼容性风险。

所以这轮变更里，一个很实用的判断标准是：凡是你现在想对 token 内容“顺手做点智能处理”的地方，优先都改成只把它当字符串。

一份不靠表格的 rollout 前检查清单

如果你的系统会用到 GitHub App installation token 或 GITHUB_TOKEN，建议按这个顺序过一遍：

• 搜代码里是否存在 len(token)==40、token.length === 40、VARCHAR(40)、CHAR(40) 这类假设
• 搜是否有 ghs_[A-Za-z0-9]{36} 或同类固定长度正则
• 检查数据库、缓存、审计表、重试队列、配置页输入框是否能容纳至少 520 字符
• 检查 secret masking、日志脱敏、代理转发、网关校验是否会因为格式变化失效
• 检查任何自定义“decode token / parse token / inspect token body”的逻辑，能删就删
• 如果你维护 GitHub Action 周边平台，额外把 GITHUB_TOKEN 相关链路也纳入扫描
• rollout 期间保留一段更细的认证失败日志，但不要把完整 token 打进日志

哪些团队最容易在 4 月底到 6 月底之间踩坑

最容易先出问题的团队

• 自研 GitHub App 中台、集成层、Bot 平台的团队
• 把 token 存进数据库或任务系统的团队
• 给 GitHub Actions 外挂了审计、网关、代理、policy 中间件的团队
• 曾经为了“更安全”加过 token 格式白名单校验的团队

风险相对可控的团队

• 全程透传 token、不做本地格式判断的团队
• 只依赖官方 SDK/官方 Actions，不自己碰 token 结构的团队
• 已经把 secrets 存储、脱敏、代理和数据库列宽做成宽松字符串处理的团队

两个常见误区

误区一：这只是 GitHub App 的事，和 Actions 无关

不对。GitHub 在 changelog 里已经明确写了，这轮 rollout 会先覆盖 GitHub Actions 发出的 GITHUB_TOKEN，以及其他 first-party featured integrations。也就是说，如果你虽然没写自定义 GitHub App，但你做了 Actions 周边平台、审计代理或企业管控层，依然可能在影响面里。

误区二：既然新格式带 JWT，那就更容易本地校验了

也不对。GitHub 说得非常明确：客户端不该依赖这个 JWT 的内容，更不该把它当成本地验证依据。对客户端来说，它依然应该是 opaque string，只是现在比过去更长、结构更复杂。

FAQ

GitHub App installation token 新格式什么时候开始 rollout？

GitHub changelog 给出的时间是从 2026-04-27 开始分阶段 rollout。第一阶段会先落到 GitHub Actions 发出的 GITHUB_TOKEN 和部分 first-party 集成，之后再逐步扩到更广泛的 GitHub App installation token。

如果我只用官方 SDK，还需要担心吗？

通常风险会小很多，但还不能直接当成零风险。因为真正容易出问题的常常不是 SDK，而是你外围的数据库、日志脱敏、代理、配置校验和内部平台层。

新 token 还是 ghs_ 开头吗？

是。GitHub 说前缀不变，installation token 仍然会以 ghs_ 开头；变化主要在后面的结构，以及整体长度从固定短串变成约 520 字符、且长度可变。

GHES 会被这轮 GitHub App installation token 变更影响吗？

按 GitHub 当前 changelog，这次变更适用于 GitHub Enterprise Cloud 和 Data Residency 环境，GitHub Enterprise Server 当前不在范围内。

结论：这轮要查的不是权限，而是你有没有把 token 写死成一种长度

回到最实际的问题：GitHub App installation token 格式要变了，你现在最该做什么？

我的建议是：别先盯着 GitHub API 能不能调通，先查你自己的长度假设、正则、列宽和解析逻辑。 因为这轮变更最可能先打断的，不是 GitHub 发 token 的能力，而是你周围那一圈“为了方便和安全顺手加上的硬编码”。

如果你们已经把 GitHub App installation token 当成 opaque string 透传，这次大概率只是一次低风险兼容性确认；反过来，如果你们系统里还残留 40 字符、固定正则、窄字段、自定义解析 这些旧假设，那么 4 月底到 6 月底这段 rollout 窗口，就值得尽快做一轮排查。

来源

• GitHub Changelog: Notice about upcoming new format for GitHub App installation tokens
• GitHub Docs: About authentication with a GitHub App
• GitHub Docs: Use GITHUB_TOKEN for authentication in workflows
• GitHub REST API Docs: Create an installation access token for an app