Tokens de instalação do GitHub App: introdução de cabeçalho de sobrescrita por solicitação

O GitHub introduziu um cabeçalho temporário de solicitação chamado X-GitHub-Stateless-S2S-Token para dar suporte à adoção gradual de um novo formato de token para tokens de instalação do GitHub App. Com esse cabeçalho, desenvolvedores podem testar antecipadamente o impacto do novo formato de token e, se necessário, manter o formato de token existente.

Principais pontos

Cabeçalho X-GitHub-Stateless-S2S-Token

Ao definir esse cabeçalho na solicitação POST /app/installations/:installation_id/access_tokens, é possível sobrescrever a decisão do lado do servidor sobre o rollout do formato de token.

Valor do cabeçalho	Efeito
enabled	Retorna um token stateless (formato JWT) independentemente do andamento do rollout.
disabled	Retorna um token stateful (opaco legado) mesmo que a integração esteja incluída no rollout.
(ausente)	Segue o comportamento normal do rollout.

Novo formato de token (JWT com prefixo ghs_)

O novo token stateless tem formato JWT com prefixo ghs_, cerca de 520 caracteres de comprimento e contém dois pontos (.). O token stateful existente é uma string opaca mais curta e não contém pontos.

Os desenvolvedores devem verificar os pontos a seguir para validar que o aplicativo lida corretamente com o novo formato de token.

• Remover suposições codificadas sobre o comprimento do token
• Atualizar regex usadas na validação do token (regex recomendada: ghs_[A-Za-z0-9\._]{36,})
• Configurar colunas do banco de dados usadas para armazenar tokens para permitir pelo menos 520 caracteres
• Garantir que código de inspeção ou validação de token trate tokens ghs_ como strings opacas

Como se preparar

1. Teste com enabled: chame o endpoint usando o cabeçalho de opt-in e confirme que o app aceita o novo formato de token de ponta a ponta.
2. Teste com disabled: confirme que o app também funciona com o formato opaco legado, garantindo operação normal caso tokens stateless fiquem temporariamente indisponíveis.
3. Remova o cabeçalho: depois que ambos os caminhos forem validados, remova o cabeçalho. O rollout do GitHub passará a gerenciar automaticamente o formato do token.

Observações

• Esse cabeçalho é temporário e deixará de ser compatível em um momento que será anunciado separadamente no futuro.
• Tokens de instalação de app existentes continuarão funcionando até expirarem.
• Essa mudança se aplica aos ambientes GitHub Enterprise Cloud e Data Residency; o GitHub Enterprise Server não é afetado.
• Rollouts futuros aplicarão o novo formato de token apenas a tokens server-to-server de instalação do GitHub App (incluindo o GITHUB_TOKEN do Actions).

Mais detalhes estão disponíveis no blog do GitHub.