GitHub アプリインストールトークン：リクエストごとのヘッダーによる上書き機能
GitHub は、2026 年 4 月に発表された新しいトークン形式のロールアウト前に、開発者がアプリやワークフローを検証できるよう、特定の POST リクエストでトークン形式を強制的に切り替える一時的なヘッダー機能を導入した。
2026 年 4 月に発表された通り、GitHub では GitHub App のインストールトークンの新しい形式の展開を開始しています。この展開があなたの環境に到達する前にアプリやワークフローを検証していただくため、必要に応じてどちらのトークン形式を強制するかを指定できる一時的なリクエストヘッダーを提供します。
ヘッダーとは何ですか？
POST /app/installations/:installation_id/access_tokens リクエストに対して X-GitHub-Stateless-S2S-Token ヘッダーを設定すると、その単一のリクエストに対するサーバー側の展開決定が上書きされます。
ヘッダー値
効果
enabled
展開のどの段階にいても、ステートレス（JWT 形式）トークンを返します。
disabled
統合機能がすでに展開に含まれている場合でも、ステートフル（クラシックな非構文トークン）トークンを返します。
(absent)
通常の展開動作（つまり、上書きなし）を行います。
それ以外の値（true, false, 1, 0 など）は静かに無視され、標準的な展開動作が適用されます。
このヘッダーは、POST /app/installations/:installation_id/access_tokens REST API でサポートされています。
使用方法
展開があなたのアプリに到達する前に、積極的にテストしてください
enabled を使用して、必要に応じてステートレストークンをリクエストし、アプリケーションがそれを正しく処理できるか検証します。
インストールアクセストークンを作成する際は、X-GitHub-Stateless-S2S-Token: enabled リクエストヘッダーを送信して、レスポンスで新しいトークン形式を強制してください。エンドポイントの詳細やリクエストの例については、「アプリ用のインストールアクセストークンの作成」に関する REST API ドキュメントをご覧ください。
ステートレス トークンは ghs_ プレフィックスを持つ JWT です。長さは約 520 文字と長く、ドットが 2 つ含まれています。一方、ステートフル トークンはドットを含まない短い不透明な文字列です。
アプリで確認すべき事項:
トークンの長さに関するハードコードされた前提条件の排除
インストール トークンを検証するために使用されるすべての正規表現は、追加のアンダースコアと JWT の存在に対応するように更新する必要があります。新しい形式と現在の形式の両方のトークンに一致させるための推奨される正規表現は ghs_[A-Za-z0-9\._]{36,} です。
トークンの保存およびヘッダー設定用のデータベース列は、少なくとも 520 文字を受け入れる必要があります
すべてのトークンイントロスペクション（内部検証）または検証コードは、ghs_ トークンを不透明な文字列として扱う必要があります
展開期間中は、より多くの時間を必要とする場合は一時的にオプトアウトしてください
展開が準備が整う前にアプリに到達した場合、ステートフル トークンの受信を継続しながらアプリケーションを更新するために、disabled に設定されたヘッダーを設定できます。
トークンタイプの検証
ghs_ プレフィックス後のドットの数を確認することで、トークンタイプを検証できます。ステートレスな JWT 形式のトークンはドットが 2 つあり、ステートフルな不透明トークンはドットがありません。
スコープ
このヘッダーは一時的なものです。今後数週間で別途発表される将来の非推奨時点では、もはや尊重されなくなります。その時点で、対象となるすべてのアプリは条件付きなしでステートレス トークンを取得します。両方のトークン形式を検証した後、プロダクション コードからこのヘッダーを削除してください。
既存のアプリインストール トークンは、有効期限が切れるまで引き続き動作します。
この変更は GitHub Enterprise Cloud およびデータレジデンシー環境に適用されます。GitHub Enterprise Server は本変更の影響を受けません。
今後のロールアウトでは、新しいトークン形式が GitHub App インストール用サーバー間トークン（Actions の GITHUB_TOKEN を含む）に対してのみ適用されます。
Copilot コードレビューフローで使用されるユーザーからサーバーへのトークンに関するフォーマット変更の詳細については、今後数週間で共有いたします。
準備方法
有効化してテストする：オプトインヘッダーを指定してエンドポイントに呼び出し出し、アプリが新しいトークン形式をエンドツーエンドで受け入れることを確認してください。
無効化してテストする：アプリが従来の不透明なフォーマットでも正常に動作することを確認し、ステートレストークンが一時的に利用できない場合にも適切にフォールバックできるよう準備しておいてください。
ヘッダーの削除：両方のパスが検証されたら、ヘッダーを削除してください。その後、GitHub のロールアウトにより自動的にトークン形式が管理されます。
この変更によってアプリのワークフローに影響が出た場合や、一時的に変更からオプトアウトする必要がある場合は、GitHub サポートまでお問い合わせください。GitHub コミュニティ内のディスカッションに参加することも可能です。
本記事「GitHub App installation tokens: Per-request override header」は、最初に The GitHub Blog で公開されました。
原文を表示
As announced in April 2026, GitHub is rolling out a new token format for GitHub App installation tokens. To help you validate your apps and workflows before the rollout reaches you, we’re providing a temporary request header that lets you force either token format on demand.
What is the header?
Setting X-GitHub-Stateless-S2S-Token on a POST /app/installations/:installation_id/access_tokens request overrides the server-side rollout decision for that single request.
Header value
Effect
enabled
Returns a stateless (JWT-format) token, regardless of where you are in the rollout.
disabled
Returns a stateful (classic opaque) token, even if your integration is already included in the rollout.
(absent)
Normal rollout behavior (i.e., no override).
Any other value (true, false, 1, 0, etc.) is silently ignored and given the standard rollout behavior.
The header is supported on the POST /app/installations/:installation_id/access_tokens REST API.
How to use it
Before the rollout reaches your app, test proactively
Use enabled to request a stateless token on demand and validate that your application handles it correctly.
When creating an installation access token, send the X-GitHub-Stateless-S2S-Token: enabled request header to force the new token format in the response. For full endpoint details and request examples, see the REST API documentation for creating an installation access token for an app.
A stateless token is a ghs_-prefixed JWT. It is longer (~520 characters) and contains two dots. In contrast, a stateful token is a short opaque string with no dots.
Things to check in your app:
No hardcoded token length assumptions
Any regex used to validate an installation token is updated to handle additional underscores and the presencce of a JWT. Our recommended regex to match both new and current format tokens is ghs_[A-Za-z0-9\._]{36,}.
Database columns for token storage and header settings accept at least 520 characters
Any token introspection or validation code treats ghs_ tokens as opaque strings
During the rollout, temporarily opt out if you need more time
If the rollout reaches your app before you’re ready, you can set the header with disabled to continue receiving stateful tokens while you update your application.
Verifying the token type
You can verify the token type by checking the number of dots after the ghs_ prefix: a stateless JWT-format token has two dots, while a stateful opaque token has no dots.
Scope
The header is temporary. At a future deprecation point, to be announced separately in the coming weeks, it will no longer be respected. At that point, all eligible apps will unconditionally receive stateless tokens. Remove the header from your production code once you have validated both token formats.
Existing app installation tokens continue to work until they expire.
This change applies to GitHub Enterprise Cloud and Data Residency environments. GitHub Enterprise Server isn’t impacted by this change.
Upcoming rollouts will apply the new token format only to GitHub App installation server-to-server tokens, including Actions GITHUB_TOKEN.
We’ll share more details in the coming weeks on planned format changes for user-to-server tokens used in Copilot code review flows.
How to prepare
Test with enabled: Call the endpoint with the opt-in header and verify your app accepts the new token format end-to-end.
Test with disabled: Confirm your app also works with the classic opaque format, so it degrades gracefully if stateless tokens are ever temporarily unavailable.
Remove the header: Once both paths are validated, remove the header. GitHub’s rollout will then automatically manage the token format.
Reach out to GitHub Support if you see this change affecting your app workflows and need to temporarily opt-out of the change. Join the discussion within GitHub Community.
The post GitHub App installation tokens: Per-request override header appeared first on The GitHub Blog.
関連記事
今日のまとめ
AI日報で今日の重要ニュースをまとめ読み