GitHub is deploying a new stateless token format for App installation tokens globally and has introduced a temporary request header enabling developers to explicitly specify token format during token creation. This feature supports smoother migration and application compatibility testing before the new token format becomes mandatory.
- Stateless JWT tokens contain two dots, stateful tokens have none
- Override token format per request via custom header
- Supports gradual app updates and compatibility verification
Infrastructure signal
GitHub is transitioning its App installation tokens from a stateful, opaque string format to a larger, stateless JWT format. The new tokens are longer and provide embedded claims that simplify token validation without server-side state checks. This shift is an infrastructure-level change aimed at improving scalability and security, as stateless tokens can be verified locally by relying parties.
To mitigate disruption during this migration, GitHub introduced the X-GitHub-Stateless-S2S-Token HTTP header for token creation requests. This lets developers override the default rollout behavior on a per-request basis. By explicitly requesting either the old or new token format, teams can evaluate interoperability, update their token handling logic, and plan infrastructural adjustments before the global rollout completes.
Developer impact
The change to a JWT-formatted installation token affects authentication workflows by requiring updated JWT handling or parsing logic deployed in apps and services consuming these tokens. Developers can now validate their readiness by forcing the new token type using the custom header on POST /app/installations/:installation_id/access_tokens calls, aiding incremental update cycles without breaking live environments.
This opportunity to opt for stateful or stateless tokens programmatically reduces risk by providing a controlled migration path. Developers should implement detection logic based on the new token’s characteristic dots count and prefix format to adapt API clients, OAuth flows, and security verifications accordingly. Additionally, the ability to fallback ensures uninterrupted deployments and rapid troubleshooting during transition periods.
What teams should watch
Platform and security teams must monitor token validation components and any dependent tooling that processes GitHub App installation tokens. Attention should be given to logging and observability metrics around token issuance failures or misconfigurations caused by token format mismatches, ensuring smooth deployment and runtime stability.
Development managers should communicate these changes to engineering teams early to allocate time for code updates, testing against both token formats, and integration with internal identity or access management infrastructures. Monitoring GitHub support channels and community discussions is advisable to track ongoing rollout status and leverage emerging best practices.