A token can arrive successfully and still break before the API request leaves your service. Check for a small assumption: a field that fits yesterday's value, a validator that recognizes only the old shape, or a formatter that changes the string.
GitHub's October 2, 2026 announcement confirms that its installation-token rollout is complete. Newly minted tokens default to the stateless ghs_APPID_JWT format, roughly 520 characters rather than 40. Permissions, repository scope and the one-hour lifetime are unchanged. The temporary override header is scheduled for deprecation on November 30, 2026.
This documentation-based guide provides an original compatibility worksheet. It does not report a tested GitHub integration. Start with invented strings in an isolated harness, never working credentials.
Define what “opaque” means in your application
GitHub's April 24 format notice says length varies and clients must not depend on the token's JWT contents or validate its internal signature. The stated scope is installation server-to-server tokens, including Actions GITHUB_TOKEN, on GitHub Enterprise Cloud and Data Residency. GitHub Enterprise Server is excluded; do not generalize this change to every GitHub token type.
Your application's contract should therefore be simple: retain the received installation token unchanged and present it to the intended GitHub endpoint. Do not extract an installation ID, permission list or expiry from its internals to drive application behavior. A 520-character example is not a permanent maximum.
This is separate from the app-signed JWT used to request an installation token. GitHub's generation documentation distinguishes that request credential from the returned token and supplies expiry and permissions in the response. Use that documented metadata instead of inventing a parser.
Draw the shortest complete token journey
Write your actual sequence: issuer response, application object, encrypted storage or cache, worker handoff, HTTP client and outbound gateway. Omit components you do not use. Add an owner beside every transition; an SDK upgrade alone cannot repair a separate storage limit.
| Boundary | Question | Evidence to record |
|---|---|---|
| Response to application | Does a schema reject unfamiliar length or punctuation? | Fixture accepted without rewriting |
| Write and readback | Can storage preserve the whole value? | Exact equality after a round trip |
| Worker or process handoff | Does serialization add quotes, spaces or a newline? | Equality at the receiving boundary |
| HTTP construction | Does the complete header reach the mock receiver? | Expected header compared in memory |
| Error reporting | Can a rejected request expose the value? | Sanitized failure record |
This worksheet is an engineering review aid, not a list of observed defects. Record “not exercised” where the harness cannot represent a production component. Keep HTTP safety checks, including rejection of newline-bearing header input; treating credentials as opaque does not mean accepting unsafe transport syntax.
Use a matrix that can catch silent damage
Build these deliberately invalid fixtures locally. They must never authenticate, leave the harness or be substituted into production configuration. Use ASCII so character and byte counts coincide in this example.
| Fixture | Construction | Expected observation |
|---|---|---|
| Legacy-shaped | ghs_ plus 36 repeated letters | All 40 characters survive |
| Long, punctuated | A 520-character invented value containing dots, underscores and hyphens | No legacy-length rejection or character replacement |
| Headroom | A 900-character invented value | No accidental 520-character ceiling |
| Near-twins | Two long values differing only near the end | They remain distinct after every round trip |
| Missing value | Absent or empty token | A controlled error before dispatch |
The 900-character case is a chosen stress fixture, not GitHub's promised token size. Set a documented operational limit appropriate to your system rather than removing every bound. For that limit, add tests just below, at and above it; oversized input should fail explicitly, never become a shorter credential.
For each case, compare the entire input and output in memory. Matching lengths alone miss substitutions. Matching the first few characters misses truncation. Keep fixture IDs and pass/fail results in reports rather than copying token-like values into shared logs.
Check failure paths before declaring compatibility
A fictional worker illustrates the trap: its database accepts the long fixture, but its job serializer silently clips a field. The later request fails authentication, making the issuer look responsible. A comparison immediately after deserialization would localize the damage. This is a hypothetical diagnosis, not a claim about any product.
In the isolated harness, inject a storage rejection, simulated unauthorized response and timeout. Check both the returned error and captured logs. Prefer excluding credential fields from logging at the source; test any remaining masking behavior across both shapes. Never introduce real tokens merely to see whether a redactor catches them.
Keep refresh behavior separate from representation. GitHub's REST reference says an expired installation token produces a 401 and requires a new token. A simulated 401 can exercise your error handler, but cannot prove that a real token was expired or that live authentication works.
Finish with a release gate and an exit date
For an already authorized integration test, GitHub's May 15 header guide documents X-GitHub-Stateless-S2S-Token on the installation-token creation request: enabled requests stateless tokens; disabled requests the older form. Other values are ignored. The guide recommends validating both and removing the override afterward.
That controlled live check is a separate step requiring an approved test installation and secure credential handling. Do not point synthetic fixtures at GitHub or widen app permissions to complete this worksheet.
- Expand restrictive storage safely before deploying code that relies on the change; preserve encryption and access controls.
- Require full-value comparisons across every represented boundary and sanitized success and failure evidence.
- Record live authentication separately from synthetic compatibility. Keep an unknown critical boundary as a release blocker until its owner supplies evidence.
- Ensure rollback code can also handle longer tokens; restoring a 40-character assumption is not a recovery plan.
- Assign an owner to remove temporary overrides before the announced November 30 deadline.
Close the review with the build, environment, boundary, fixture, observed result, unresolved limit and owner. The useful result is a token journey that preserves the value without depending on its internal shape.