Coollab.pt

[email protected]: permission denied (publickey). — Guia completo para resolver esse erro e manter seus repositórios GitHub funcionando

17 Janeiro 2026 Por Innehallsteam Não
Pre

Introdução ao problema: entender o que significa [email protected]: permission denied (publickey).

Ao trabalhar com Git e GitHub você pode encontrar a mensagem de erro [email protected]: permission denied (publickey). em momentos cruciais, como ao clonar, puxar ou enviar alterações para um repositório remoto via SSH. Esse aviso não é apenas técnico: ele é um sinal claro de que o SSH não conseguiu autenticar com as chaves públicas configuradas. Entender as raízes desse problema é essencial para manter seu fluxo de trabalho ágil, evitar bloqueios e proteger o acesso aos seus projetos. Neste guia, exploraremos as causas mais comuns, as melhores práticas para gerar, gerenciar e distribuir chaves SSH, além de soluções específicas para diferentes sistemas operacionais e cenários de uso.

Visão geral do SSH e da autenticação com GitHub

GitHub oferece suporte a autenticação por SSH, que utiliza pares de chaves criptográficas: uma chave pública e uma chave privada. A chave pública fica gravada no GitHub, associada à sua conta, enquanto a chave privada fica no seu computador, protegida por permissões de arquivo. Quando você tenta acessar um repositório remoto via SSH (por exemplo, [email protected]), o servidor do GitHub verifica se a chave pública correspondente à sua chave privada está autorizada. Se houver qualquer discrepância — uma chave ausente, mal configurada, protegida por senha inadequadamente, ou se o agente SSH não está carregando a chave — ocorre o erro [email protected]: permission denied (publickey).

Principais causas do erro [email protected]: permission denied (publickey).

A seguir estão as situações mais comuns que geram esse problema, ordenadas pela frequência de ocorrência. Conhecê-las ajuda a priorizar a solução de forma eficiente.

Chave SSH ausente ou não vinculada ao GitHub

Se você nunca gerou uma chave SSH ou se a chave pública correspondente não foi adicionada à sua conta do GitHub, o servidor não conseguirá autenticar. [email protected]: permission denied (publickey). aparece justamente porque não há uma chave autorizada para o usuário associado ao repositório.

Chave SSH incorreta ou de uso errado

Em ambientes com várias chaves SSH (por exemplo, chaves de trabalho, acadêmicas ou pessoais), pode haver conflito entre chaves. O GitHub tende a aceitar apenas a chave pública correta associada ao usuário correto. Caso o ssh tente usar uma chave que não está cadastrada no GitHub, o erro ocorrerá.

Permissões de arquivo inadequadas

O SSH exige permissões estritas para a chave privada. Se o arquivo de chave tem permissões muito amplas (por exemplo, 0777) ou se o diretório ~/.ssh não tem permissões apropriadas, o cliente SSH pode recusar a usar a chave por motivos de segurança.

Agente SSH não carregando a chave

O agente SSH gerencia as chaves na memória para facilitar o uso repetido. Se a chave correta não estiver carregada no agente, o SSH não conseguirá apresentá-la ao GitHub, resultando no erro.

Configuração incorreta no arquivo SSH

Arquivos de configuração como ~/.ssh/config podem infligir instruções que direcionam o cliente SSH para chaves ou hosts errados. Uma configuração malformada pode levar o SSH a tentar usar uma chave inexistente ou inadequada para github.com.

Problemas com a URL do repositório

Se você estiver tentando acessar o repositório via HTTPS ou com uma URL SSH que não corresponde ao host esperado, a autenticação pode falhar. Verifique se a URL está realmente apontando para [email protected] ou para o host correto.

Como diagnosticar o problema de forma rápida

Antes de partir para soluções profundas, algumas verificações simples podem indicar a causa do problema. Siga estas etapas em ordem para diagnosticar com precisão.

Teste básico de autenticação com o GitHub

Execute:

ssh -T [email protected]

Se o resultado for algo como “Hi username! You’ve successfully authenticated, but GitHub does not provide shell access.”, então a autenticação está funcionando, e o problema pode estar na configuração do repositório ou no caminho da SSH. Caso contrário, o retorno mostrará a natureza do erro, incluindo informações úteis para correção.

Verificação de chaves disponíveis no sistema

Digitar:

ls -l ~/.ssh

Procure por chaves comuns, como id_rsa, id_ecdsa ou id_ed25519 e seus arquivos públicos correspondentes (com a extensão .pub).

Confirmação de presença da chave pública no GitHub

Entre na sua conta GitHub, acesse as configurações de SSH e GPG keys, e confirme se a chave pública correspondente a sua chave privada está listada. Se não estiver, você precisará adicionar a chave pública.

Verificação de permissões dos arquivos SSH

As permissões recomendadas são:

  • Chave privada: chmod 600 ~/.ssh/id_rsa (ou o nome da sua chave)
  • Chave pública: chmod 644 ~/.ssh/id_rsa.pub
  • Diretório .ssh: chmod 700 ~/.ssh

Permissões inadequadas podem impedir o SSH de usar a chave, gerando o erro [email protected]: permission denied (publickey).

Como gerar e configurar uma chave SSH do zero

Se você ainda não possui uma chave SSH ou precisa de uma chave dedicada para GitHub, siga este passo a passo. Ter uma chave dedicada facilita a gestão de acessos e aumenta a segurança do seu ambiente de desenvolvimento.

Gerar uma nova chave SSH

Abra o terminal e execute:

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

Quando solicitado, escolha um caminho seguro e, se desejar, configure uma passphrase. A recomendação atual é usar ED25519 por ser mais moderno e seguro.

Adicionar a chave pública ao GitHub

Copie o conteúdo do arquivo público recém-criado (por exemplo, ~/.ssh/id_ed25519.pub) e cole na seção SSH keys das configurações da sua conta GitHub. Dê um nome descritivo para facilitar a identificação, especialmente se você usa várias máquinas.

Conferir a configuração do SSH

Depois de adicionar a chave no GitHub, teste novamente com:

ssh -T [email protected]

Você deve ver a mensagem de boas-vindas correspondente à sua conta. Caso haja qualquer mensagem de erro, revise as etapas anteriores.

Gerenciar o SSH Agent para autenticações contínuas

O SSH Agent facilita o uso de chaves sem precisar inserir a passphrase repetidamente. Configure-o para carregar suas chaves ao iniciar o sistema, especialmente em ambientes de desenvolvimento que exigem acessos frequentes a repositórios remotos.

Iniciar o agente SSH e adicionar a chave

Em sistemas Unix-like:

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

Se a chave estiver protegida por passphrase, você será solicitado a fornecê-la apenas uma vez. Em máquinas com várias chaves, repita o processo para cada uma que você usa com GitHub.

Configurações comuns no arquivo ~/.ssh/config

Você pode simplificar o uso de SSH para GitHub com entradas no arquivo de configuração. Exemplo:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Essa configuração garante que, ao se conectar a github.com, o SSH utilize a chave especificada, reduzindo conflitos com outras chaves presentes no sistema.

Resolvendo cenários específicos com [email protected]: permission denied (publickey).

Alguns cenários requerem abordagens particularizadas para evitar o erro. Abaixo, descrevemos situações comuns e as soluções correspondentes.

Cenário A: Você tem várias chaves SSH

Quando existem várias chaves no sistema, o SSH pode tentar uma chave que não está cadastrada no GitHub. Adotar uma configuração por host, como mostrado acima, evita que o SSH use uma chave incorreta para github.com.

Cenário B: Alteração de domínio ou uso de aliases

Se você usa domínios ou aliases para o GitHub (por exemplo, enterprise ou outras instâncias), verifique se o Host no arquivo ~/.ssh/config está correto e se a chave correspondente foi adicionada ao host específico.

Cenário C: Ambientes Windows

No Windows, especialmente com Git Bash ou WSL, o ajuste de permissões e o uso de OpenSSH podem exigir etapas adicionais. Utilize o Git Bash para comandos SSH ou configure o OpenSSH no Windows com cuidado, sempre garantindo que as chaves estejam no diretório correto e com as permissões adequadas. Em alguns casos, é necessário reiniciar o serviço de SSH ou o terminal após alterações.

Cenário D: Chaves com passphrase e automação

Se a chave tem passphrase e você precisa de automação (por exemplo, pipelines CI/CD), considere usar uma chave sem passphrase para operações automatizadas ou usar segredos gerenciados para fornecer a passphrase de forma segura. Avalie as políticas de segurança da sua organização antes de optar por uma chave sem passphrase.

Boas práticas para evitar o [email protected]: permission denied (publickey).

Adotar boas práticas ajuda a reduzir a recorrência desse tipo de erro e facilita a gestão de acessos em equipes. Abaixo estão recomendações fundamentais.

1) Mantenha chaves separadas por máquina e por propósito

Para cada máquina ou projeto, use uma chave distinta. Isso facilita revogações rápidas em caso de comprometimento de uma máquina sem impactar outros ambientes.

2) Use chaves modernas e seguras

Prefira chaves ED25519, que oferecem bom equilíbrio entre segurança e desempenho. Evite chaves muito antigas (RSA com tamanho pequeno) que já não atendem aos padrões de segurança atuais.

3) Regularmente revise as chaves cadastradas no GitHub

Faça um inventário periódico das chaves cadastradas em sua conta GitHub. Remova aquelas que não são utilizadas há muito tempo ou que pertencem a dispositivos desativados.

4) Configure avisos de segurança

Quando possível, utilize ferramentas de conformidade que alertam sobre alterações nas chaves SSH ou no acesso a repositórios. Isso ajuda a detectar usos não autorizados rapidamente.

5) Documente o fluxo de autenticação da sua equipe

Crie um guia interno com as etapas para gerar, registrar e revogar chaves SSH. Uma documentação clara reduz a curva de aprendizado para novos membros da equipe e evita erros repetidos.

Alternativas de autenticação: quando usar HTTPS em vez de SSH

Embora SSH seja uma opção robusta para autenticação, o uso de HTTPS com token de acesso pessoal (PAT) pode ser mais simples em alguns cenários, especialmente em ambientes corporativos com políticas rígidas de rede. Em [email protected]: permission denied (publickey)., considerar a troca para HTTPS pode resolver problemas de chaves rapidamente, desde que você tenha os mecanismos de autenticação corretos configurados (PAT ou credentials manager).

Como mudar de SSH para HTTPS para um repositório existente

Para alterar a URL remota de SSH para HTTPS, use:

git remote set-url origin https://github.com/username/repo.git

Depois disso, você pode usar um gerenciador de credenciais para armazenar o PAT, simplificando os pushes sem precisar inserir a senha a cada operação. Embora haja menos foco em chaves públicas, essa abordagem pode ser valiosa para equipes com políticas que dificultam o gerenciamento de chaves SSH.

Casos de uso real: passos práticos para erros comuns

Nesta seção, trazemos cenários práticos que você pode encontrar no dia a dia e as soluções diretas para cada um. A cada passo, o objetivo é resolver o erro [email protected]: permission denied (publickey). com eficiência e clareza.

Caso 1: Não há chave pública cadastrada no GitHub

Passo a passo:

  1. Gerar uma nova chave SSH (ED25519).
  2. Copiar o conteúdo da chave pública
  3. Adicionar ao GitHub em Settings > SSH and GPG keys
  4. Testar com ssh -T [email protected]

Caso 2: A chave correta não está carregada no agente

Passos:

  1. Iniciar o agente SSH: eval "$(ssh-agent -s)"
  2. Adicionar a chave: ssh-add ~/.ssh/id_ed25519
  3. Testar novamente com ssh -T [email protected]

Caso 3: Permissões de arquivo inadequadas

Verifique e ajuste:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Após ajustar, tente novamente com o comando de teste.

Caso 4: Configuração incorreta no arquivo ~/.ssh/config

Verifique se há entradas conflitantes para github.com ou Servidores SSH; se houver, comente ou ajuste. Um exemplo simples de configuração correta já citado pode evitar problemas.

Checklist final para garantir que o [email protected]: permission denied (publickey). não volte

Use esta lista rápida para confirmar que não houve falha recorrente:

  • Chave SSH cadastrada no GitHub correspondente à máquina atual.
  • Permissões corretas em ~/.ssh e arquivos de chave.
  • Chave carregada no SSH agent quando necessário.
  • Configuração correta em ~/.ssh/config para github.com.
  • URL remota correta (SSH) configurada no repositório local.

Conclusão: mantendo a continuidade do seu fluxo de trabalho

O erro [email protected]: permission denied (publickey). pode parecer técnico, mas frequentemente é resolvido com passos simples de diagnóstico, geração de novas chaves quando necessário e uma configuração cuidadosa do SSH. Ao adotar boas práticas de gerenciamento de chaves, manter a documentação atualizada e conhecer as soluções rápidas para cenários comuns, você reduz drasticamente o tempo de inatividade e aumenta a segurança da sua conta e de seus repositórios. Lembre-se de que a chave correta, registrada na conta certa, combinada com uma configuração estável do SSH, é a base para um acesso confiável ao GitHub por SSH e evita interrupções no seu dia a dia de desenvolvimento.

Recursos adicionais para aprofundar o tema

Para quem busca ampliar o conhecimento sobre autenticação SSH com GitHub, aqui vão sugestões de leitura prática e recursos oficiais que ajudam a manter o seu ambiente seguro e funcional. Embora este artigo já cubra o essencial, explorar a documentação atualizada é sempre uma boa prática, visto que os serviços de hospedagem de código continuam evoluindo.

Documentação oficial do GitHub sobre autenticação SSH

A documentação do GitHub traz orientações detalhadas sobre como gerar chaves, adicioná-las à conta e solucionar problemas comuns. A leitura é útil para confirmar práticas recomendadas e conhecer alterações que possam impactar seu fluxo de trabalho.

Guia de SSH do OpenSSH

O OpenSSH é a implementação de referência para SSH em sistemas Unix-like. Consultar o guia oficial pode esclarecer dúvidas sobre opções de linha de comando, permissões, agentes e autenticação com chaves.

Ferramentas de gerenciamento de senhas e segredos

Para equipes, adotar ferramentas de gerenciamento de segredos ajuda a manter chaves privadas fora de texto simples no código ou em repositórios, reduzindo o risco de exposição acidental.

Boas práticas de segurança para chaves SSH

Acompanhar práticas modernas de segurança, como rotação de chaves, uso de passphrases fortes e auditorias periódicas, aumenta a resiliência do seu ambiente de desenvolvimento diante de eventuais violações.

Resumo prático

Se você chegou até aqui com o [email protected]: permission denied (publickey). em tela, lembre-se do fluxo essencial: verifique a existência da chave pública cadastrada, confirme as permissões corretas, garanta que o SSH agent esteja carregando a chave, ajuste o arquivo de configuração se necessário e valide a conexão com ssh -T [email protected]. Em muitos casos, essa sequência resolve de forma rápida o problema, permitindo que você retome seus trabalhos com GitHub sem interrupções.

Chamadas à ação para leitores

Gostou do guia? Compartilhe com colegas que estejam enfrentando o mesmo desafio. Se tiver dúvidas específicas ou cenários que não foram cobertos, deixe um comentário com o seu caso particular. Responderemos com soluções adaptadas ao seu ambiente, seja ele Linux, macOS ou Windows, garantindo que o erro [email protected]: permission denied (publickey). não volte a atrapalhar o seu fluxo de trabalho.

CategoriaPrevenir ameacas