GitHub CLI agora pode usar tokens que expiram: seus scripts estão preparados?

Se você usa a GitHub CLI para entrar na conta e também copia seu token para outros programas, vale revisar essa integração antes de ativar a novidade. Em 21 de outubro, o GitHub anunciou uma prévia pública de credenciais OAuth com prazo de validade e renovação automática, disponível a partir da CLI 2.103.0.

A ferramenta é o programa chamado pelo comando gh no terminal. A prévia é opcional: os logins existentes e os tokens fornecidos manualmente continuam com o comportamento anterior quando você não adere ao recurso.

O cuidado é para scripts e extensões que ativarem essa opção e guardarem uma cópia do token para usar mais tarde. O acesso passa a expirar em poucas horas. Quando a credencial salva vencer, o script pode parar de autenticar mesmo que a GitHub CLI consiga renovar o token para os próprios comandos.

A CLI consegue renovar a própria credencial. Um programa que guardou uma cópia do token pode continuar tentando usar o valor antigo.

Quando você escolhe uma credencial com validade limitada, a CLI guarda um token de acesso de curta duração e um token de renovação que também é substituído durante o processo. O primeiro autoriza as chamadas; o segundo permite obter uma nova credencial de acesso. A ferramenta cuida dessa renovação quando precisa autenticar.

O benefício é reduzir o tempo em que um token de acesso vazado pode ser usado. Segundo o GitHub, ele deixa de funcionar em poucas horas, em vez de permanecer válido por tempo indeterminado. Isso não dispensa a proteção dos arquivos e do ambiente em que as credenciais ficam armazenadas.

A opção está disponível a partir da versão 2.103.0. Você pode ativá-la em um login específico ou configurá-la para novos logins. O servidor precisa aceitar credenciais renováveis; quando não aceita, a CLI volta para um token sem expiração conforme o comportamento atual.

O anúncio informa suporte no github.com e no ghe.com. No GitHub Enterprise Server, as credenciais renováveis são emitidas a partir do GHES 3.23. Em versões anteriores do servidor, solicitar a opção mantém o comportamento sem expiração.

Imagine uma integração que lê o token da CLI pela manhã e o grava na configuração de outro programa. Mais tarde, a CLI renova a credencial de acesso para continuar funcionando. O outro programa ainda tem a cópia original, que pode já ter vencido. É possível, portanto, um comando da CLI funcionar e a integração separada apresentar erro de autenticação.

A correção depende de como a integração foi feita. Se o outro programa aceita consultar a CLI quando precisa de uma credencial, use esse caminho. Se a rotina lê gh auth token, faça a leitura novamente quando for usar o token, em vez de conservar o resultado entre execuções. Em processos longos, uma leitura feita apenas no início também pode envelhecer antes da próxima chamada.

Isso não exige espalhar tokens novos por arquivos nem publicar o valor no log para conferir se mudou. O que precisa ser corrigido é a forma como o programa obtém a credencial. Se ele só aceita um token fixo e não há como adaptá-lo agora, o próprio GitHub recomenda adiar a adesão à prévia nesse fluxo.

Revise rotinas que executam gh auth token e salvam a saída em uma variável permanente, arquivo de configuração ou segredo de CI. Também merecem atenção extensões e ferramentas que recebem o token uma vez e tentam reaproveitá-lo em execuções futuras.

Se o processo chama comandos pela própria CLI, a renovação pode acontecer automaticamente. Se outro programa precisa ler o token, obtenha uma credencial atualizada a cada execução em vez de copiar o valor para uso contínuo. Se um fluxo depende de uma credencial que permaneça válida por muito tempo, deixe a opção desligada para esse fluxo até adaptá-lo.

Para operações Git por HTTPS, o GitHub recomenda configurar a CLI como gerenciador de credenciais. A empresa também recomenda Git 2.46 ou posterior, que consegue identificar credenciais expiradas e evita mantê-las em cache além do prazo.

Confira primeiro qual versão está instalada. A novidade exige a GitHub CLI 2.103.0 ou posterior. Se seus scripts usam apenas os comandos da CLI e você quer testar a prévia, faça isso em uma máquina de desenvolvimento ou em um fluxo que não dependa de um token permanente:

gh --version
gh auth login --expiring
gh auth status

O primeiro comando mostra a versão. O segundo inicia um login solicitando uma credencial renovável. O terceiro informa a conta autenticada e o estado da credencial. A flag --expiring ativa a opção nesse login; você não precisa mudar todos os ambientes de uma vez.

Para pedir a opção em cada login futuro, o GitHub também documenta uma configuração global. Use-a somente depois de revisar as automações que dependem do token:

gh config set expiring_credentials enabled

Em Git por HTTPS, você pode pedir à CLI para fornecer e renovar as credenciais usadas pelo Git. Confira a versão instalada antes de depender do tratamento de cache recomendado pelo GitHub:

git --version
gh auth setup-git

Confira se o login usa credenciais com validade limitada e descubra de onde o script lê o token. Se a rotina salvou a saída de gh auth token, altere o processo para obter uma credencial atualizada perto do momento de uso. Para Git por HTTPS, use o gerenciador configurado com gh auth setup-git. Outros programas precisam ter suporte a essa integração ou ser adaptados para consultar a credencial.

Uma forma simples de investigar é executar gh auth status no mesmo ambiente do script e conferir a versão de gh e Git. Não imprima o conteúdo do token no log: ele funciona como uma credencial de acesso. Em automações, mantenha permissões restritas e evite armazenar tokens em arquivos versionados.

Esta novidade é diferente do pedido temporário de autenticação que pode aparecer ao clonar repositórios públicos. Naquele caso, o GitHub pode pedir login em operações HTTPS anônimas durante tráfego incomum; aqui, a mudança é uma escolha sobre o prazo e a renovação dos tokens da CLI.

Antes de ativar a prévia em produção, procure cada lugar que copia ou armazena o resultado de gh auth token.