GitHub Appインストールトークン: リクエストごとのオーバーライドヘッダーを導入

GitHubは、GitHub Appインストールトークン向けの新しいトークン形式の段階的導入をサポートするため、X-GitHub-Stateless-S2S-Token という一時的なリクエストヘッダーを導入しました。このヘッダーにより、開発者は新しいトークン形式の影響を事前にテストし、必要に応じて既存のトークン形式を維持できます。

主な内容

X-GitHub-Stateless-S2S-Token ヘッダー

POST /app/installations/:installation_id/access_tokens リクエスト時にこのヘッダーを設定することで、サーバー側のトークン形式ロールアウト判定を上書きできます。

ヘッダー値	効果
enabled	ロールアウト状況に関係なく、ステートレス（JWT形式） トークンを返します。
disabled	統合がロールアウト対象に含まれていても、ステートフル（従来の不透明） トークンを返します。
(なし)	通常のロールアウト動作に従います。

新しいトークン形式（ghs_ 接頭辞のJWT）

新しいステートレストークンは ghs_ 接頭辞が付いたJWT形式で、長さは約520文字と長く、2つのドット（.）を含みます。既存のステートフルトークンは短い不透明な文字列で、ドットは含まれません。

開発者は、アプリケーションが新しいトークン形式を正しく処理できることを検証するため、次の点を確認する必要があります。

• トークン長に関するハードコードされた前提を排除する
• トークン検証に使われる正規表現を更新する（推奨正規表現: ghs_[A-Za-z0-9\._]{36,}）
• トークン保存用のデータベースカラムが最低520文字以上を許容するよう設定する
• トークンの検査または検証コードが ghs_ トークンを不透明な文字列として扱う

準備方法

1. enabled でテスト: オプトインヘッダーを使ってエンドポイントを呼び出し、アプリが新しいトークン形式をエンドツーエンドで受け入れるか確認します。
2. disabled でテスト: アプリが従来の不透明形式でも動作することを確認し、ステートレストークンが一時的に利用できない場合でも正常に動作することを確認します。
3. ヘッダーを削除: 両方の経路の妥当性を確認したらヘッダーを削除します。GitHubのロールアウトがトークン形式を自動的に管理します。

参考事項

• このヘッダーは一時的なもので、今後あらためて告知される時点でサポート終了予定です。
• 既存のアプリインストールトークンは、有効期限が切れるまで引き続き動作します。
• この変更はGitHub Enterprise CloudおよびData Residency環境に適用され、GitHub Enterprise Serverは影響を受けません。
• 今後のロールアウトでは、GitHub Appインストールのサーバー・ツー・サーバートークン（Actions GITHUB_TOKEN を含む）にのみ新しいトークン形式が適用される予定です。

詳細は GitHubブログ を確認してください。