Resolvendo Erros Comuns de Autenticação no Git Usando SSH e Tokens

A maioria dos problemas de autenticação no Git se resume a uma incompatibilidade entre a URL remota, a credencial que o Git está tentando usar e as permissões na conta de hospedagem do Git. O texto do erro pode parecer dramático, mas a correção geralmente é mecânica depois que você sabe qual caminho o Git está seguindo.

Comece com a URL remota:

git remote -v

Se você vir https://github.com/org/repo.git, o Git está usando HTTPS e precisará de um nome de usuário mais um token ou um auxiliar de credenciais que possa fornecê-lo. Se você vir [email protected]:org/repo.git, o Git está usando SSH e precisará de uma chave privada que corresponda a uma chave pública registrada no host.

Não misture os dois durante a solução de problemas. Escolha HTTPS ou SSH, faça a URL remota corresponder e teste esse caminho diretamente.

Leia o erro literalmente

fatal: Authentication failed for 'https://...' geralmente significa que o Git alcançou o servidor, mas não apresentou uma credencial HTTPS válida. A credencial antiga pode estar em cache, o token pode ter expirado ou o token pode não ter acesso a esse repositório.

remote: Permission to org/repo denied ou 403 Forbidden geralmente significa que sua identidade foi reconhecida, mas não tem permissão para a operação. Por exemplo, você pode estar usando um token da conta errada, um token sem acesso de escrita ou uma chave SSH anexada a um usuário diferente.

Permission denied (publickey) significa que o SSH não ofereceu uma chave que o servidor aceita.

Um prompt repetido de nome de usuário/senha via HTTPS geralmente significa que o Git continua recebendo uma rejeição e perguntando novamente. Digitar a senha da sua conta repetidamente não ajudará em hosts que exigem tokens para operações Git.

Corrigindo HTTPS com um token de acesso pessoal

Para remotos HTTPS, crie um token de acesso pessoal nas configurações da sua conta do host Git. Os nomes exatos dos menus diferem entre GitHub, GitLab, Bitbucket e plataformas auto-hospedadas, mas a forma é a mesma: crie um token, dê a ele acesso ao repositório, defina uma expiração que corresponda à política da sua organização e copie-o imediatamente.

Quando o Git solicitar, use seu nome de usuário normal e cole o token como senha:

Username: seu-usuario
Password: <cole-o-token-aqui>

Use as permissões mais restritas que funcionam. Para um repositório privado para o qual você faz push, você precisa de acesso de leitura e escrita ao repositório. Para clonar repositórios públicos, você pode não precisar de um token. Tokens refinados e regras de SSO da organização podem adicionar outra camada: um token pode existir, mas ainda precisa de aprovação ou autorização SSO antes de acessar um repositório da empresa.

Se o Git nunca solicitar o novo token, provavelmente está usando uma credencial antiga em cache. Limpe a entrada armazenada para o host e tente novamente.

No macOS, verifique o Acesso às Chaves (Keychain Access) por entradas relacionadas ao seu host Git, como github.com ou git:https://github.com.

No Windows, abra o Gerenciador de Credenciais (Credential Manager) e remova a credencial genérica relevante para o host.

No Linux, inspecione seu auxiliar configurado:

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

O auxiliar cache armazena credenciais temporariamente na memória. O auxiliar store as escreve no disco em texto simples, a menos que você configure uma camada de armazenamento mais segura, então use-o com cuidado. O sistema de auxiliares de credenciais do Git é projetado para pedir credenciais aos auxiliares e permitir que eles salvem as bem-sucedidas; a segurança depende do auxiliar que você escolher.

Uma sequência útil de redefinição HTTPS é:

git remote -v
git config --show-origin --get-all credential.helper
# remova a credencial antiga do armazenamento de credenciais do SO
git ls-remote origin

git ls-remote origin é um teste limpo porque contata o remoto sem alterar sua árvore de trabalho.

Corrigindo SSH com chaves

Para remotos SSH, primeiro verifique se você já tem chaves:

ls -al ~/.ssh

Nomes comuns de chaves incluem id_ed25519, id_rsa e nomes específicos de host como github_work_ed25519. O arquivo .pub é a chave pública que você envia para o host Git. O arquivo sem .pub é privado e não deve ser compartilhado.

Se você precisar de uma nova chave, Ed25519 é um bom padrão em sistemas modernos:

ssh-keygen -t ed25519 -C "[email protected]"

Use uma frase secreta, a menos que seu ambiente tenha um motivo específico de automação para não usar. Em seguida, adicione a chave pública à sua conta do host Git ou às configurações de chave de implantação:

cat ~/.ssh/id_ed25519.pub

Teste a conexão diretamente:

ssh -T [email protected]

Para GitLab ou Bitbucket, substitua o nome do host. Um teste bem-sucedido geralmente imprime uma saudação ou uma mensagem informando que o acesso ao shell não é fornecido. Isso é normal; a autenticação Git-over-SSH ainda pode funcionar.

Se o SSH ainda falhar, pergunte ao cliente SSH o que ele está fazendo:

ssh -vT [email protected]

Procure linhas mostrando quais chaves estão sendo oferecidas. Se sua chave não for oferecida, carregue-a no agente:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Para várias contas no mesmo host, use ~/.ssh/config para que o Git saiba qual chave pertence a qual remoto:

Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/github_work_ed25519
  IdentitiesOnly yes

Em seguida, aponte o repositório para esse alias:

git remote set-url origin git@github-work:org/repo.git

Isso evita o problema comum em que o SSH oferece sua chave pessoal para um repositório de trabalho.

Alternando protocolos de forma limpa

Se sua equipe padronizar o SSH, altere um remoto HTTPS assim:

git remote set-url origin [email protected]:ORG/REPO.git

Se sua empresa bloquear SSH ou exigir inspeção HTTPS, altere para o outro lado:

git remote set-url origin https://github.com/ORG/REPO.git

Depois de alterar a URL, teste com uma operação de leitura:

git fetch origin

Em seguida, teste a ação que falhou:

git push origin HEAD

Se o fetch funcionar, mas o push falhar, a autenticação provavelmente é válida e a autorização é o problema. Verifique a proteção de branch, função do repositório, escopo do token e regras de SSO da organização.

Ambientes de CI e servidor

Em agentes de build e servidores, evite usar o token pessoal de um humano quando possível. Prefira chaves de implantação, usuários de máquina ou o armazenamento de credenciais integrado do seu sistema de CI. Mantenha os segredos fora do histórico de comandos e logs. Não cole tokens em URLs remotas assim, a menos que você esteja em um ambiente descartável controlado:

https://[email protected]/org/repo.git

Esse estilo pode vazar por logs, listas de processos, histórico do shell e arquivos de configuração.

Para Jenkins, runners do GitHub Actions, runners do GitLab e sistemas similares, armazene credenciais no mecanismo de segredos da plataforma e injete-as apenas para o trabalho que precisa delas.

Uma lista de verificação rápida

Execute estes comandos em ordem quando estiver travado:

git remote -v
git ls-remote origin

Se a URL for HTTPS, limpe as credenciais antigas em cache e use um token atual com as permissões corretas do repositório.

Se a URL for SSH, execute:

ssh -T git@seu-hostname
ssh -vT git@seu-hostname

Confirme se a chave esperada está sendo oferecida e se sua metade pública está registrada na conta correta.

Se a autenticação for bem-sucedida, mas o push falhar, procure regras de autorização: branches protegidos, função de escrita ausente, autorização SSO expirada, chaves de implantação somente leitura ou tokens sem permissão de escrita.

A correção confiável não é tentar senhas aleatórias. Combine o protocolo remoto com o tipo de credencial, remova credenciais em cache obsoletas, teste a conexão diretamente e, em seguida, verifique as permissões no repositório.