GitHub's November 2026 App Token Cutoff Explained: Treat Tokens as Opaque

Things break in odd places: database writes fail, validation checks reject good tokens and logs print secrets in full. The cause is the new GitHub App installation token format. GitHub made it the default for new tokens, and tokens grew from 40 characters to about 520.

Picture a common setup. A small team runs a GitHub App that comments on pull requests, or proposed code changes, when a dependency (a library the code relies on) has a risky licence. The app saves each token in PostgreSQL, a popular open-source database, in a column declared VARCHAR(40): text of at most 40 characters. The setup is made up, but the problem is real.

When GitHub's staged rollout reached the app in June, token writes started failing. The quick fix was a request header that asks GitHub for old-style tokens. That header stops working on 30 November 2026, so the team needs a real fix.

You need five terms: GitHub App, installation, installation access token, JWT and opaque. Stateful and stateless get their own section below.

• GitHub App: an integration that acts on repositories with its own identity and permissions, like the review bot.
• Installation: one organisation or account that has added the app.
• Installation access token: a password the app gets from GitHub to act inside one installation. It expires after one hour and starts with ghs_.
• JWT: a JSON Web Token. A signed JWT is three encoded parts joined by two dots, and the last part is a signature, or a similar check value, that proves who issued it.
• Opaque: you store and send the value, but never look inside it or check its shape.

The token travels in the Authorization header, the part of an HTTP request that carries credentials. S2S in the header name means server-to-server: the app acting as itself for an installation, not on behalf of a person.

The new GitHub App installation token format is ghs_APPID_JWT: the old ghs_ prefix, the app's ID, an underscore, then a JWT. A GitHub-internal issuer, a GitHub service that creates and signs tokens, signs that JWT. GitHub puts the length at about 520 characters and says it varies.

GitHub's 2 October changelog lists what did not change: token permissions, repository scoping, the one-hour expiry and the REST endpoint. That is the web address apps call to create tokens through GitHub's API, the interface programs use to talk to GitHub. Tokens minted before the switch keep working until they expire.

GitHub's April notice and 15 May changelog name GitHub Enterprise Cloud and Data Residency, GitHub's hosted offerings, as in scope. The April notice also names the GITHUB_TOKEN, the token that GitHub Actions, GitHub's built-in automation service, gives each workflow run. The 2 October changelog covers all newly minted installation tokens.

Only GitHub Enterprise Server, the version companies host themselves, is named as unaffected. As of 19 October 2026, its docs pages still carry the same rollout note, so check your version's release notes.

One detail is still loose. As of 19 October 2026, GitHub has published no maximum length, only about 520 characters and a request for room for at least 520. Size storage with headroom, and do not treat 520 as a ceiling.

A stateful token is a reference to a record the issuer keeps. A stateless token carries signed facts, so the issuer can check it with a key instead of a lookup. GitHub uses both words: stateful for the old format, stateless for the new one.

The idea is older than GitHub's change. The OAuth 2.0 standard, RFC 6749, says an access token may be an identifier used to fetch stored details. It may also contain those details in a verifiable way. The same section says the string is usually opaque to the client.

Think of a railway cloakroom slip and a stamped gate pass. The cloakroom slip is the stateful token: it means nothing until the clerk finds the matching shelf. The gate pass is the stateless token: the guard checks the stamp, not a register.

Where the picture breaks: you could read a printed gate pass, but you should not read GitHub's token. GitHub says a client app cannot validate its signature, and GitHub can change what the token carries.

GitHub's stated reason is speed and reliability. The 2 October changelog says the format makes token issuance and validation faster and improves the reliability of the GitHub API. The April notice says the JWT holds details such as the target installation and the app.

Because GitHub owns what is inside and has told you not to rely on it. The April notice says the JWT is signed by a GitHub-internal issuer and cannot and should not be validated by a client app. It adds that client apps must not depend on its contents.

You also do not need to look. The response that creates the token already includes expires_at, the expiry time, and the permissions granted. Read those fields and pass the token along untouched.

Opaque also means not assuming the new shape. GitHub's 15 May changelog asks you to test with the classic format too, so your app degrades gracefully if stateless tokens are temporarily unavailable. Code that requires dots is as fragile as code that requires 40 characters.

Anything that stores, checks, forwards or prints a token with the old shape in mind. GitHub's 2 October changelog lists four places to look, and the review bot had a problem in each.

Storage: columns, secret stores and environment variables

What a 40-character column does with a longer token depends on the database. We ran it on PostgreSQL 16.15 and SQLite 3.45.1, and took MySQL's behaviour from its 8.4 manual. An explicit cast is code that converts a value to a type, and strict SQL mode is a MySQL setting that turns bad data into errors.

A cut token is the worst case. The write succeeds, but the stored string is no longer the token GitHub issued, so the failure shows up later as a rejected API call. GitHub asks that token columns hold at least 520 characters, and the same goes for secret stores and environment variables with a small limit. Secret stores are vaults for passwords, and environment variables are settings passed to a program at start.

Validation: regexes that expect the old pattern

A regex, or regular expression, is a text pattern. Some apps checked tokens against ghs_[A-Za-z0-9]{36} before saving them. GitHub's April notice names that exact pattern as one to remove. The new token has dots and extra underscores, so it never matches.

Proxies, gateways and middleware

Proxies, gateways and middleware are servers or code layers that sit between your app and GitHub and pass requests on. GitHub warns that some truncate or reject long Authorization headers.

Common defaults are far larger than 520 characters. For example, nginx accepts a request header field up to its 8k (8 kilobyte) buffer by default. Limits someone set by hand are what bite, so search proxy configs for them.

Logs, redaction and secret scanners

Redaction means masking secrets before a line is written to a log. A rule built on the old pattern does not match the new token, so the token is printed. A secret scanner, a tool that checks code for passwords before each commit, has the same blind spot.

If you are new to this, you can stop here. You know what changed, why tokens must stay opaque and where code breaks. The rest is for engineers making the fix: redaction rules tested line by line, the header deadline and a checklist with expected output.

Use a pattern that finds both formats, and use it only to find and mask tokens, never to judge them. GitHub's 15 May changelog recommends ghs_[A-Za-z0-9\.\-_]{36,} for matching both new and current format tokens.

Finding a token in a log line is detection, and a loose pattern is right there. Rejecting a token that fails a pattern is validation. GitHub's April notice recommends against validating tokens with hardcoded patterns. Its 15 May checklist offers this regex for any check you keep, but we use it only to find tokens.

Old rules leave most of the token in the log

Pause and predict. Some apps redacted with ghs_\w{36}, where \w means a letter, digit or underscore. How much of a new token does that rule hide?

We tested four rules on Python 3.13.16. The new token was synthetic: ghs_, an app ID and a JWT we signed with our own key, 524 characters long. It has the same shape as GitHub's, not GitHub's contents.

What just happened? Two old rules mask a prefix and print the rest. A quick test can even look like success, because the line does contain the mask. A public issue in GitHub's own gh-aw-firewall repository flags its ghs_ masking patterns as broken by the new format.

Mask the finished log line, not one logger

A common first try is a logging.Filter attached to your app's logger. We tested that on Python 3.13.16 and it leaked the full token twice. It missed records from child loggers, such as review_bot.refresher under review_bot, and it missed exception tracebacks.

The child logger leak is documented: Python's logging manual says a logger's filter does not apply to events from descendant loggers. The safer place is the formatter. A handler sends log lines to a destination, such as the console or a file, and its formatter builds each final line.

import logging
import re

# GitHub's published pattern (15 May 2026): matches old and new ghs_ tokens
GHS_TOKEN = re.compile(r"ghs_[A-Za-z0-9\.\-_]{36,}")


class RedactingFormatter(logging.Formatter):
    def format(self, record):
        # Build the full line first (message, args, traceback), then mask it
        return GHS_TOKEN.sub("ghs_REDACTED", super().format(record))


handler = logging.StreamHandler()
handler.setFormatter(RedactingFormatter("%(name)s %(levelname)s %(message)s"))
logging.basicConfig(handlers=[handler], level=logging.INFO)

log = logging.getLogger("review_bot.refresher")
log.warning("retrying with %s", "ghs_123456_aaaa.bbbb.cccc_dddd_eeee_ffff_gggg")

Run it and you should see one line: review_bot.refresher WARNING retrying with ghs_REDACTED. Because the formatter masks the finished line, it also covers arguments, other modules and tracebacks you log with log.exception. We checked all three on Python 3.13.16. Uncaught exceptions and print calls skip logging, so they stay unmasked.

Two notes for production. Set this formatter on every handler that writes logs, because a handler with a plain formatter prints the raw line. The pattern also swallows a full stop right after a token, which is harmless for masking.

Give your pre-commit secret scanner the same pattern, so a leaked new token is caught before it reaches the repository.

GitHub stops honouring it. The 2 October changelog says the header will be deprecated on 30 November 2026, and after that all eligible apps always receive stateless tokens. As of 19 October 2026, that post does not define eligible.

GitHub added the header on 15 May 2026 for testing. You send it with the POST request to /app/installations/INSTALLATION_ID/access_tokens that creates an installation token. The value enabled asks for a stateless token, and disabled asks for the old stateful one.

Any other value, such as true or 1, is silently ignored and gets the normal rollout behaviour. Since GitHub reported the rollout complete on 2 October, normal behaviour now means a stateless token. When GitHub added the header in May, it gave no end date. The 2 October changelog is where GitHub states 30 November.

Find every place a token is stored, checked, forwarded or printed, fix it, test both formats, then delete the header. Here is the review bot's plan, with a check for the steps that change data.

1. 1

   Search the code

   Search for ghs_, the number 40, VARCHAR(40), {36} and X-GitHub-Stateless-S2S-Token. Include proxy, log shipper and secret scanner config.

2. 2

   Widen storage

   Run ALTER TABLE install_tokens ALTER COLUMN token TYPE text. Check it with psql, PostgreSQL's command-line tool: \d install_tokens should show the type text for the token column. Check secret store and environment variable limits too.

3. 3

   Delete validation regexes

   Remove checks like ghs_[A-Za-z0-9]{36}. GitHub's REST docs say an expired token gets 401 Unauthorized, the HTTP error code for a rejected credential. Let the API be the judge.

4. 4

   Fix the edges

   Raise any hand-set proxy or gateway header limits. Switch log redaction and secret scanners to GitHub's pattern for both formats.

5. 5

   Test both formats in staging

   In staging, a test copy of production, run the full bot with the header set to enabled, then disabled, before 30 November. Watch for 401 errors, failed writes and unmasked tokens.

6. 6

   Check what was stored

   After a fresh token is saved, run SELECT max(length(token)) FROM install_tokens. Expect a number near 520 characters, not 40. Use this as a one-off check, never as code that gates tokens.

7. 7

   Remove the header

   Delete the override header from production code before 30 November 2026, as GitHub asks.

After the change, the token refresher stores whatever GitHub returns and never inspects it. Here db is a psycopg 3 connection, the PostgreSQL driver for Python, and your app commits as it normally does.

import requests


def refresh_install_token(api_base, app_jwt, installation_id, db):
    resp = requests.post(
        f"{api_base}/app/installations/{installation_id}/access_tokens",
        headers={
            "Authorization": f"Bearer {app_jwt}",
            "Accept": "application/vnd.github+json",
        },  # no X-GitHub-Stateless-S2S-Token header any more
        timeout=10,
    )
    resp.raise_for_status()
    body = resp.json()
    token = body["token"]  # opaque: never split, decode or length-check it
    db.execute(
        "UPDATE install_tokens SET token = %s, expires_at = %s WHERE installation_id = %s",
        (token, body["expires_at"], installation_id),
    )
    return token

We ran this function with requests 2.32.5 and psycopg 3.2.10 against a local stand-in for the token endpoint and a PostgreSQL 16.15 table. It sent no override header and stored a 524-character synthetic token unchanged. The UPDATE assumes each installation already has a row; with none, PostgreSQL updates nothing and raises no error.

Pointed at a VARCHAR(40) column, the same call failed with the error value too long for type character varying(40). That is the failure the team saw in June.

Frame it as a story about token design and trusting contracts, not GitHub internals.

1. 1

   State the change

   GitHub installation tokens moved from 40-character opaque strings to stateless ghs_ tokens of about 520 characters. GitHub reported the rollout complete on 2 October 2026.

2. 2

   Contrast stateful and stateless

   Stateful tokens point to a record the issuer stores. Stateless tokens carry signed facts that the issuer checks with a key.

3. 3

   Name the contract

   Clients can rely on the API response and its expires_at field, not on the token's length or inner layout.

4. 4

   List what breaks

   Fixed-width columns, validation regexes, hand-set proxy header limits, and redaction or scanning rules tied to the old pattern.

5. 5

   Give the fix and the date

   Store tokens as opaque text, detect them with a loose pattern, test both formats and drop the override header before 30 November 2026.