Git e SSH em Ação: git@github.com: permission denied (publickey) e Como Resolver de Forma Completa

O erro git@github.com: permission denied (publickey) é uma das mensagens mais comuns que surgem quando se tenta interagir com repositórios no GitHub usando SSH. Ele pode aparecer ao tentar clonar, puxar (pull) ou enviar alterações (push). A boa notícia é que, na maioria dos casos, a solução envolve um conjunto simples de verificações e procedimentos para garantir que a chave pública correta esteja associada à sua conta e que o cliente SSH esteja configurado adequadamente. Neste guia abrangente, vamos explorar desde as causas básicas até soluções avançadas, com passos práticos, exemplos e dicas para diferentes sistemas operacionais.

git@github.com: permission denied (publickey): o que significa

Quando você vê a mensagem git@github.com: permission denied (publickey), o Git/SSH está dizendo que não reconhece a sua identidade com a chave SSH fornecida. Em termos simples, o GitHub não conseguiu verificar se você é quem diz ser usando a chave pública disponível no seu usuário. Existem várias razões para isso acontecer, incluindo chaves ausentes, chaves não adicionadas à conta, permissões incorretas de arquivos, ou configuração incorreta do cliente SSH.

Principais causas do erro

Chave SSH ausente ou não carregada

Se você nunca gerou uma chave SSH ou se o agente SSH não está carregando a chave, o GitHub não encontrará a identidade correspondente. Sem uma chave carregada, a autenticação falha com o erro permission denied.

Chave pública não associada à conta GitHub

Mesmo que você tenha uma chave SSH no seu computador, é essencial que a chave pública correspondente esteja adicionada à sua conta GitHub. Do contrário, o serviço não reconhecerá a sua identidade.

Configuração incorreta do SSH

Arquivos de configuração, como ~/.ssh/config, podem direcionar automaticamente a autenticação para uma chave diferente daquela que está cadastrada no GitHub, gerando o erro git@github.com: permission denied (publickey).

Permissões inadequadas nos arquivos SSH

O SSH é rigoroso quanto às permissões de arquivo. Chaves privadas devem ter permissões restritivas, caso contrário, o cliente SSH pode recusá-las. Configurações de permissões muito abertas impedem a utilização da chave.

Agente SSH não carregou a chave

O ssh-agent gerencia chaves em memória. Se o agente não estiver carregando a chave certa, as tentativas de autenticação vão falhar com o erro descrito.

Como diagnosticar rapidamente o problema

Verifique a existência da chave SSH

Abra o terminal e liste as chaves no diretório ~/.ssh:

ls -la ~/.ssh

Você deverá ver arquivos como id_rsa e id_rsa.pub (ou outras pares de chave). Se não houver, você precisará gerar uma nova chave SSH.

Teste a autenticação SSH com GitHub

Use o comando abaixo para confirmar se o Git consegue se conectar via SSH com o GitHub:

ssh -T git@github.com

Se tudo estiver correto, você deve ver uma mensagem como: “Hi <username>! You’ve successfully authenticated, but GitHub does not provide shell access.” Caso contrário, a mensagem deve indicar o problema, como chave não encontrada ou permissão negada.

Verifique se a chave pública está na sua conta GitHub

Entre no GitHub > Configurações > SSH and GPG keys. Confirme se a chave pública correspondente (por exemplo, id_rsa.pub) foi adicionada. Se não estiver, copie o conteúdo do arquivo ~/.ssh/id_rsa.pub e adicione como nova chave SSH.

Confirme as permissões de arquivos SSH

As permissões devem ser, por exemplo:

• chmod 700 ~/.ssh
• chmod 600 ~/.ssh/id_rsa
• chmod 644 ~/.ssh/id_rsa.pub

Chaves com permissões muito abertas podem ser rejeitadas pelo SSH.

Verifique o agente SSH

Certifique-se de que o agente está rodando e carregando a chave correta:

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

Se a chave não estiver listada, adicione-a com ssh-add.

Gerando e adicionando novas chaves SSH

Gerar nova chave SSH

Para gerar uma nova chave SSH, use:

ssh-keygen -t rsa -b 4096 -C "seu@email.exemplo"

O parâmetro -C adiciona um rótulo para identificar a chave. Siga as instruções para definir o caminho (padrão: ~/.ssh/id_rsa) e, opcionalmente, uma passphrase para maior segurança.

Adicionar chave pública ao GitHub

Copie a chave pública gerada:

cat ~/.ssh/id_rsa.pub

Copie o conteúdo e, em GitHub, vá para Configurações > SSH and GPG keys > New SSH key. Cole a chave, dê um título e salve.

Teste a conexão novamente

Após adicionar a chave ao GitHub, teste a conexão:

ssh -T git@github.com

Você deve receber a mensagem de boas-vindas, confirmando que a autenticação está funcionando com a nova chave.

Configuração avançada do SSH

Configurar um arquivo SSH específico para o GitHub

Para gerenciar várias identidades, crie ou edite ~/.ssh/config com entradas como:

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

Essa configuração garante que, sempre que você se conectar ao github.com, a chave correta seja utilizada.

Entendendo o impacto do known_hosts

O arquivo ~/.ssh/known_hosts armazena as identidades de hosts conhecidos. Se ocorrerem mudanças no host (por exemplo, substituição de servidor), pode ser necessário excluir entradas antigas para evitar mensagens de host fora de identidade.

Utilizar chaves com ERROS de passphrase

Uma passphrase protege a chave privada. Para shells automatizados, é comum usar chaves sem passphrase, entendendo os riscos, mas mantendo a prática recomendada de usar uma passphrase forte para chaves sensíveis.

Alternativas: SSH vs HTTPS

Quando considerar usar HTTPS

Se o problema com SSH persiste ou se você prefere uma abordagem menos complexa de autenticação, usar o URL HTTPS do repositório pode ser uma alternativa. Authenticating with HTTPS geralmente utiliza token ou senha (ou o GitHub CLI). No entanto, trabalhar com SSH costuma ser mais conveniente para fluxos de trabalho com várias operações de push e pull.

Como mudar para HTTPS temporariamente

Para clonar com HTTPS, use o comando:

git clone https://github.com/usuario/repo.git

Para alternar repositório existente para HTTPS:

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

Boas práticas para gerenciamento de identidades SSH

Gerencie várias chaves com perfis distintos

Se você trabalha com várias contas (pessoal, empresa, projetos), utilize o SSH config para definir Host e IdentityFile diferentes para cada domínio ou host.

Proteja suas chaves com passphrase

Uma passphrase forte adiciona uma camada extra de segurança, especialmente em laptops que podem ser perdidos ou roubados.

Rotina de atualização de chaves

Atualize periodicamente suas chaves SSH e remova chaves que não estejam mais em uso para reduzir a superfície de ataque.

Erros comuns por sistema operacional

Windows

No Windows, muitas pessoas usam o Git Bash ou o Windows Subsystem for Linux (WSL). Se ocorrer git@github.com: permission denied (publickey), verifique se a chave está na pasta C:\Users\\.ssh e se o ssh-agent está carregando a chave. Em alguns casos, o PuTTY/ Pageant pode estar em execução e interferir; prefira o uso de OpenSSH embutido no Git for Windows para evitar conflitos.

macOS

O macOS costuma vir com OpenSSH atualizado. Verifique permissões com chmod e assegure-se de que o agente SSH está ativo. O Terminal pode exigir permissões adicionais para acessar a chave se houver restrições de segurança.

Linux

Em distribuições Linux, a solução típica envolve confirmar a chave em ~/.ssh, ajustar permissões, registrar a chave com o ssh-agent e garantir que o GitHub tenha a chave pública correspondente. A consistência entre id_rsa e id_rsa.pub é essencial.

Perguntas frequentes

Posso usar uma chave com passphrase?

Sim. Usar uma passphrase aumenta a segurança, exigindo a senha para desbloquear a chave privada cada vez que o SSH a utiliza. Em ambientes de automação, você pode integrar com ferramentas de gerenciamento de segredo para evitar inserções manuais repetidas, ou utilizar chaves com uma passphrase bem protegida e um agente para facilitar o uso.

O que fazer se a chave já está publicada?

Se alguém publicou sua chave pública, revogue a chave na GitHub Settings > SSH and GPG keys e gere uma nova. Em seguida, atualize o repositório remoto para usar a nova chave pública associada à sua conta.

Como remover uma chave antiga do GitHub?

Vá para GitHub > Configurações > SSH and GPG keys, localize a chave antiga e clique em Delete. Em seguida, adicione a nova chave pública correspondente para manter o acesso sem interrupções.

A importância de manter o conceito claro

Entender por que o erro git@github.com: permission denied (publickey) ocorre ajuda a criar um fluxo de trabalho mais robusto. Ao diagnosticar rapidamente se o problema é de chave ausente, de configuração de SSH, de permissão de arquivos ou de associação à conta GitHub, você garante menos tempo perdido e mais foco no desenvolvimento. Além disso, conhecer as diferenças entre SSH e HTTPS permite escolher a abordagem que melhor atende ao seu ambiente, equipe e políticas de segurança.

Resumo passo a passo para resolver git@github.com: permission denied (publickey)

• Verifique se existe uma chave SSH no diretório ~/.ssh (id_rsa, id_rsa.pub).
• Teste a conexão SSH com ssh -T git@github.com.
• Confirme que a chave pública (id_rsa.pub) está adicionada à sua conta GitHub.
• Assegure permissões corretas em ~/.ssh e nos arquivos de chave.
• Carregue a chave no ssh-agent com eval “$(ssh-agent -s)” e ssh-add ~/.ssh/id_rsa.
• Considere usar um arquivo de configuração SSH para gerenciar várias identidades.
• Se necessário, gere uma nova chave e associe-a ao GitHub. Teste novamente.
• Como alternativa, use HTTPS para operações Git até restabelecer SSH.

Conclusão

O erro git@github.com: permission denied (publickey) não precisa ser motivo de frustração. Com uma abordagem estruturada — verificar chaves, confirmar associações com a conta, ajustar permissões e configurar o SSH corretamente — você retorna ao fluxo de trabalho com rapidez e segurança. Ao adotar práticas como o uso de SSH config para gerenciar múltiplas identidades e a adoção de passphrase para suas chaves, você aumenta a confiabilidade do seu ambiente de desenvolvimento. Lembre-se: a chave para resolver esse problema está na organização das suas chaves, na validação de cada etapa e na escolha da autenticação que melhor se adapta ao seu cenário de trabalho. Com paciência e método, o acesso ao GitHub ocorre de forma estável e segura, mantendo o foco no que realmente importa: o código e a colaboração.