GitHub CLI token expirado: como ativar renovação automática

Resposta rápida

Se o GitHub CLI ou o Git por HTTPS começou a falhar porque um token expirou, atualize o gh para a versão 2.103.0 ou mais recente, autentique-se com gh auth login --expiring e execute gh auth setup-git. Depois, confira a conta, o tipo da credencial e a expiração com gh auth status. Em operações Git, use Git 2.46 ou mais recente para evitar que outro helper mantenha em cache um acesso já vencido.

Se a falha está em um script ou extensão, procure por gh auth token executado uma única vez e por variáveis ou arquivos que guardam essa saída. Com a credencial renovável, obtenha o token novamente em cada uso; o GitHub CLI renova o acesso quando necessário. Não espere essa renovação de GH_TOKEN, GITHUB_TOKEN ou de um token fornecido manualmente: esses valores externos não são atualizados pelo gh.

O que mudou no GitHub CLI 2.103.0

Em 21 de outubro de 2026, o GitHub abriu uma prévia pública de credenciais OAuth expiráveis e renováveis no GitHub CLI. Ao aderir, o gh armazena um token de acesso de curta duração junto de um refresh token rotativo e solicita um novo acesso quando necessário. O objetivo é reduzir a janela de uso de um token de acesso vazado sem exigir novo login a cada expiração.

A mudança é opcional e compatível com logins existentes: nada muda até você pedir a credencial renovável. Ela está disponível em github.com e ghe.com; o GitHub Enterprise Server passa a emiti-la a partir da versão 3.23. Em um host sem suporte, a opção solicita o novo formato, mas o servidor pode devolver uma credencial comum não expirável.

Atualize e faça a adesão com segurança

Antes de autenticar, confirme a origem do binário e a versão em execução. O recurso exige GitHub CLI 2.103.0 ou posterior. Em uma máquina compartilhada ou com várias contas, identifique o host e a conta ativa antes de substituir qualquer login. O fluxo pelo navegador mantém a credencial no cofre do sistema quando ele está disponível; sem um cofre funcional, o gh pode oferecer armazenamento em texto simples, o que exige uma decisão de risco separada.

Para preferir credenciais expiráveis em todos os logins futuros, use a configuração expiring_credentials. Essa preferência não converte silenciosamente o login já salvo: faça uma nova autenticação para o host que deseja migrar e valide o resultado. Não copie o token exibido para um ticket, histórico, arquivo .env ou gerenciador de tarefas.

• Execute gh --version e confirme 2.103.0 ou uma versão posterior.
• Rode gh auth status e anote apenas host e conta; não use --show-token.
• Faça o login com gh auth login --expiring e escolha o host e o protocolo corretos.
• Opcionalmente, rode gh config set expiring_credentials enabled para preferir esse formato em logins futuros.
• Execute gh auth status outra vez e confirme que a credencial é renovável e mostra a expiração.

Configure o Git por HTTPS para pedir um token válido

Um token renovável só ajuda o Git por HTTPS se o GitHub CLI participar da entrega da credencial. Rode gh auth setup-git para configurar o gh como helper nos hosts autenticados, ou informe --hostname quando quiser limitar a mudança. Assim, cada operação pode receber um acesso válido sem gravá-lo na URL remota.

O GitHub recomenda Git 2.46 ou mais recente porque essa versão permite ao gh marcar a credencial expirável como não armazenável além da validade. Em versões anteriores, o gh ainda pode funcionar, mas um helper de cache intermediário pode reapresentar um token vencido. Verifique git --version e revise git config --show-origin --get-all credential.helper antes de apagar qualquer configuração global.

• Atualize o Git para 2.46 ou mais recente quando usar a credencial renovável com HTTPS.
• Execute gh auth setup-git --hostname github.com, ajustando o host quando necessário.
• Confirme que git remote -v não contém usuário, token ou outro segredo na URL.
• Teste primeiro com git ls-remote e depois com fetch, pull ou push conforme a permissão esperada.
• Se o erro persistir, compare gh auth status, helpers configurados e GitHub Status antes de refazer o login.

Corrija scripts e extensões que guardam gh auth token

O principal ponto de quebra é capturar a saída de gh auth token uma vez e reutilizá-la horas depois. Com acesso expirável, o valor salvo deixa de funcionar mesmo que o GitHub CLI ainda tenha um refresh token válido. Faça a chamada imediatamente antes da requisição que precisa do segredo, limite o tempo em memória e descarte a saída ao concluir.

Não registre o token para depuração e não o passe em argumento visível na lista de processos. Quando possível, deixe o próprio gh executar a operação, como em gh api, ou use entrada padrão e cabeçalhos construídos apenas em memória. Para processos longos, não presuma que um token lido no início continuará válido até o fim; obtenha um acesso novo antes de cada lote ou requisição protegida.

• Pesquise por gh auth token, --show-token, GH_TOKEN e GITHUB_TOKEN no código e na configuração.
• Remova arquivos, caches e variáveis persistentes que guardam a saída do gh auth token.
• Busque o token novamente imediatamente antes do uso, sem imprimi-lo em stdout ou logs.
• Teste uma renovação em ambiente de baixo risco e confirme que o processo aceita a troca de valor.
• Revogue a credencial e trate o caso como exposição se algum token apareceu em log ou artefato.

Não confunda login interativo com automação

O fluxo renovável do gh foi desenhado para a credencial armazenada pelo GitHub CLI. Em scripts não interativos, o GitHub documenta GH_TOKEN para github.com e ghe.com, e GH_ENTERPRISE_TOKEN para GitHub Enterprise Server. No GitHub Actions, use o GITHUB_TOKEN fornecido pelo job por meio de GH_TOKEN e conceda apenas as permissões necessárias.

Tokens fornecidos por variável de ambiente não são renovados pelo gh. Se uma automação externa precisa de identidade durável, não tente transformá-la em uma sessão pessoal permanente: use GitHub App, OIDC ou o mecanismo recomendado pelo serviço, com credenciais curtas e escopo mínimo. Separe claramente a sessão humana do computador e a identidade do workload.

Erros comuns e como separar a causa

Um 401 depois de algumas horas costuma apontar para valor capturado e reutilizado; uma solicitação repetida de credenciais no git pode indicar helper incorreto, Git antigo ou outro cache à frente do gh. Já Repository not found, 403, falha de SSO ou permissão insuficiente não são corrigidos apenas renovando o acesso. Confirme host, conta, escopos e acesso ao repositório.

Ao alterar escopos com gh auth refresh, preserve a preferência por credencial expirável usando --expiring ou a configuração global; do contrário, a troca de escopos pode substituir a sessão por uma credencial não expirável. Consulte o GitHub Status para descartar indisponibilidade ampla, mas lembre que uma página verde não valida seu cofre local, helper, política de SSO ou script.

• Use gh auth status sem mostrar o token e confirme host, conta e expiração.
• Teste gh api user para separar a sessão do gh de uma falha exclusiva do Git por HTTPS.
• Revise git config --show-origin --get-all credential.helper e a versão do Git.
• Cheque SSO, escopos e acesso ao repositório quando houver 403 ou Repository not found.
• Verifique o GitHub Status no horário do erro antes de alterar credenciais em massa.

Limitações e próxima ação útil

Este guia foi verificado em 22 de outubro de 2026. A credencial expirável está em prévia pública, depende do GitHub CLI 2.103.0 ou posterior e do suporte do host. O GitHub informa que pretende torná-la padrão futuramente, mas ela ainda é opcional. Políticas corporativas, SSO, cofres do sistema, helpers de terceiros e versões antigas do Git podem alterar o comportamento observado.

Comece por uma estação de desenvolvimento de baixo risco: atualize gh e Git, ative o login expirável, configure o helper, valide gh auth status e execute uma operação Git por HTTPS. Depois inventarie extensões e scripts que leem gh auth token; corrija o cache antes de ampliar a adesão. Registre o host, as versões e o resultado, nunca o segredo.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• GitHub CLI: Opt in to expiring, auto-refreshing OAuth tokensGitHub Changelog
• GitHub CLI 2.103.0GitHub
• Authenticating with GitHub CLIGitHub Docs
• gh auth loginGitHub CLI
• gh auth setup-gitGitHub CLI
• Caching your GitHub credentials in GitGitHub Docs
• GitHub StatusGitHub