Token do GitHub e autenticação no Git: personal access token, Git Credential Manager, push sem senha

Por que o Git não aceita mais a senha do GitHub

Se ao executar git push você digita o usuário e a senha do github.com e recebe uma recusa, não é um erro de digitação. Desde 13 de agosto de 2021, o GitHub desativou o acesso por senha para as operações do Git por HTTPS. No lugar da senha é preciso usar um token de acesso pessoal (personal access token, PAT) ou a autenticação pelo navegador feita pelo Git Credential Manager.

A mensagem de erro tem esta aparência:

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/... for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/user/project.git/'

O motivo é simples: a senha da conta dá acesso total a tudo, não pode ser limitada a um repositório e é trabalhosa de revogar. O token, por outro lado, é criado para uma tarefa, tem prazo de validade e um conjunto de permissões, e se vazar é removido em um minuto, sem trocar a senha. GitLab e Bitbucket seguiram o mesmo caminho, então o que está descrito a seguir se aplica, em essência, a eles também.

Duas formas de autenticação: HTTPS e SSH

O Git se comunica com o repositório remoto por um de dois protocolos, e disso depende a forma de login.

A chave SSH é configurada uma vez, e a partir daí o Git nem pede usuário ou senha. A criação e o cadastro dela no GitHub estão detalhados no artigo sobre a configuração do Git; aqui vamos nos concentrar no HTTPS, em que os iniciantes costumam ver o pedido de senha. Para descobrir qual protocolo o seu repositório usa, execute:

git remote -v
origin  https://github.com/user/project.git (fetch)
origin  https://github.com/user/project.git (push)

Como criar um token do GitHub (personal access token)

O personal access token é uma sequência longa e aleatória que o GitHub entrega no lugar da senha para acesso programático. Os tokens classic começam com ghp_, e os fine-grained, com github_pat_. O token é exibido uma única vez, logo após a criação, então copie-o para o seu gerenciador de senhas.

Passo a passo

1. Entre no github.com, clique no seu avatar no canto superior direito e abra Settings.
2. Na parte de baixo do menu lateral, escolha Developer settings e depois Personal access tokens.
3. Escolha o tipo: Fine-grained tokens (recomendado) ou Tokens (classic), e clique no botão para gerar um novo.
4. Dê um nome claro (por exemplo, «notebook, trabalho»), uma validade e as permissões.
5. Clique em gerar e copie o token imediatamente.

Fine-grained ou classic

O token fine-grained é limitado a repositórios específicos e a permissões individuais. Para o trabalho normal com código, selecione os repositórios necessários e, nas permissões de repositório, marque Contents: Read and write; isso basta para clone, pull e push. Se você apenas lê um repositório privado, basta Read-only.

O token classic vale para todos os seus repositórios de uma vez. Para fazer push em um repositório é preciso o escopo repo, e para alterar arquivos em .github/workflows, também workflow. O classic é mais simples, mas mais perigoso: se vazar, dá acesso à conta inteira.

Validade

O GitHub oferece algumas durações e permite escolher uma data. É possível criar um token sem validade, mas não é recomendável: um token eterno esquecido é uma falha de segurança clássica. O razoável é entre 30 e 90 dias, renovando quando chegar o lembrete que o GitHub envia por e-mail antes da expiração.

Git push e git clone com token

Usar o token é mais simples do que parece: o Git pergunta «Password», e você cola o token no lugar da senha.

$ git push origin main
Username for 'https://github.com': seu-usuario
Password for 'https://seu-usuario@github.com': <cole o token>

No terminal, os caracteres da senha não aparecem; isso é normal. Cole o token e pressione Enter. No Git Bash do Windows, a colagem funciona com Shift+Insert ou com o botão direito do mouse.

Git clone with token

Um repositório privado é clonado da mesma forma: o git clone pede o usuário e o token. Se você quiser evitar as perguntas (por exemplo, em um script), o token pode ser colocado diretamente no endereço:

git clone https://seu-usuario:<TOKEN>@github.com/user/project.git

Há um inconveniente: o endereço com o token fica salvo em .git/config e pode acabar no histórico do shell. Depois de clonar, remova o token do endereço:

git remote set-url origin https://github.com/user/project.git

Em sistemas de CI, o token é passado como variável de ambiente secreta, nunca gravado em arquivo. No GitHub Actions já existe o token integrado GITHUB_TOKEN para o repositório atual, então muitas vezes um PAT não é necessário.

GitLab: git clone com token

No GitLab, o token é criado nas configurações do perfil, na seção Access tokens; para trabalhar com código são necessários os escopos read_repository e write_repository. O esquema é o mesmo: o usuário do GitLab como nome e o token como senha.

git clone https://oauth2:<TOKEN>@gitlab.com/group/project.git

O GitLab aceita o nome oauth2 para qualquer token pessoal; no lugar dele você também pode usar o seu próprio usuário.

Git pull e fetch

Em um repositório público, git pull e git clone funcionam sem autenticação. Usuário e token só são pedidos para repositórios privados ou para git push. Se um pull em um projeto público pedir senha, o mais provável é que o endereço tenha um erro de digitação: o GitHub responde a um repositório inexistente da mesma forma que a um privado.

Git Credential Manager: o que é

Digitar o token a cada push é incômodo. Essa tarefa é assumida pelo credential helper: um programa auxiliar que o Git chama quando precisa de credenciais. O Git passa a ele o endereço do servidor, e o programa devolve usuário e senha (ou token) do seu armazenamento.

O Git Credential Manager (GCM) é o mais cômodo desses auxiliares. É um programa multiplataforma da GitHub e da Microsoft: no primeiro push ele abre uma janela ou o navegador para você entrar no GitHub (inclusive com autenticação em dois fatores), e o GCM obtém o token e o guarda no armazenamento seguro do sistema. Nesse caso não é preciso criar o PAT manualmente.

O GCM funciona com GitHub, GitLab, Bitbucket e Azure DevOps. No Git para Windows ele é instalado por padrão; é a opção de credential helper que aparece no instalador.

Os tipos de credential.helper

Configurar a autenticação do Git no Windows, macOS e Linux

Para ver qual helper já está configurado:

git config --show-origin --get-all credential.helper

Windows

Se você deixou as configurações padrão ao instalar o Git, o GCM já funciona: no primeiro push pelo Git Bash, PowerShell ou VS Code, abrirá a janela de login no GitHub. Se o helper não estiver configurado, ative-o manualmente:

git config --global credential.helper manager

macOS

No Mac, o Git normalmente já usa o osxkeychain: o token digitado uma vez vai para o Keychain. Para o login pelo navegador, instale o Git Credential Manager (por exemplo, com o Homebrew: brew install --cask git-credential-manager); ele mesmo se registra na configuração.

Linux

No Linux, o GCM é instalado separadamente (pacote .deb ou arquivo das versões do projeto), depois é configurado e o armazenamento é escolhido:

git-credential-manager configure
git config --global credential.credentialStore secretservice

Em um servidor sem interface gráfica é mais prático um cache temporário:

git config --global credential.helper 'cache --timeout=3600'

Alternativa para o GitHub: gh auth login

Se você tiver o GitHub CLI instalado, o comando gh auth login conduz o login pelo navegador, e gh auth setup-git configura o Git para pegar as credenciais do gh. É uma forma prática de «entrar no Git Bash» com um único comando.

Como apagar ou atualizar a senha salva no Git

A situação mais comum: o token expirou ou você trocou de conta, mas o Git continua usando os dados antigos e responde Authentication failed. É preciso apagar o registro salvo; no próximo push, o Git perguntará de novo.

Comando universal

Funciona com qualquer helper:

printf "protocol=https\nhost=github.com\n\n" | git credential reject

Git reset credentials no Windows

Abra o «Painel de Controle» → «Gerenciador de Credenciais» → «Credenciais do Windows», encontre os registros do tipo git:https://github.com e remova-os. O mesmo pode ser feito pela linha de comando:

cmdkey /list | findstr git
cmdkey /delete:git:https://github.com

Se você usa o GCM, há também o comando próprio para sair da conta: git credential-manager github logout <usuario>.

macOS

Abra o «Acesso às Chaves» (Keychain Access), procure a entrada github.com do tipo «senha da Internet» e apague-a. Ou pelo terminal:

git credential-osxkeychain erase
host=github.com
protocol=https

Depois da última linha, pressione Enter mais uma vez para enviar a linha vazia.

Linux e store

Para o store, apague a linha com github.com do arquivo ~/.git-credentials; para o cache, execute git credential-cache exit.

Erros de autenticação e como corrigi-los

Support for password authentication was removed

Você digitou a senha da conta. Crie um token e cole-o no campo Password, ou configure o Git Credential Manager. Se o erro se repete sem pedir a senha, a senha antiga está salva no armazenamento: apague-a como descrito acima.

git push: Authentication failed

Causas, da mais para a menos frequente: o token expirou; o token foi revogado; o token fine-grained não tem acesso a este repositório ou a permissão Contents está só para leitura; no armazenamento há dados de outra conta. Verifique a validade e as permissões do token em Developer settings e apague as credenciais salvas.

remote: Permission denied (403)

A autenticação funcionou, mas a sua conta não tem permissão de escrita neste repositório. O proprietário precisa adicioná-lo como Collaborator, ou você pode trabalhar pelo seu fork e abrir um pull request.

Repository not found

Em um repositório privado o GitHub não revela se ele existe, então com um token errado responde «not found». Confira o endereço com git remote -v e as permissões do token.

Git clone pede a senha toda vez

O credential helper não está configurado. Ative o manager ou o osxkeychain: depois da primeira entrada bem-sucedida, o Git deixa de perguntar. Outra opção é passar para o SSH.

Como guardar o token com segurança

• Dê o mínimo de permissões: um token fine-grained para os repositórios necessários, em vez de um classic com repo.
• Defina uma validade e gere um token novo em vez de estender indefinidamente o antigo.
• Não coloque tokens em commits nem nos endereços do remote. Se um token chegar a um repositório público, o GitHub pode revogá-lo automaticamente, mas considere-o comprometido e remova-o você mesmo.
• Use o armazenamento do sistema (GCM, Keychain) em vez do store.
• Um token por máquina ou por tarefa: assim, se vazar, você revoga apenas aquele.

Resumo

A senha do GitHub não funciona para o Git por HTTPS desde 2021. Há três caminhos válidos: entrar pelo Git Credential Manager no navegador, criar um token do GitHub e digitá-lo no lugar da senha, ou passar para as chaves SSH. O token é criado em Settings → Developer settings, e quem o guarda é o credential.helper; se aparecer Authentication failed, quase sempre basta gerar o token de novo e apagar as credenciais antigas. A conexão com o GitHub e o trabalho com repositórios remotos são explicados com prática no curso de Git.