Como Criar e Configurar Chave SSH para GitHub

Se você já tentou fazer push para um repositório no GitHub e recebeu o erro Permission denied (publickey), provavelmente precisa configurar uma chave SSH. Este tutorial mostra como resolver isso de forma definitiva. (Existe a alternativa de continuar no HTTPS usando um Personal Access Token, mas com SSH você configura uma vez e nunca mais se preocupa com tokens expirando.)

💻 Usa Windows? Todos os comandos deste post funcionam igual no Git Bash, que já vem instalado com o Git para Windows. A única exceção é o chmod, que não se aplica — o Windows gerencia permissões de arquivo de outra forma.

Por que usar SSH?

O SSH (Secure Shell) oferece várias vantagens sobre HTTPS:

Segurança: Autenticação baseada em criptografia de chave pública
Conveniência: Não precisa digitar senha nem token a cada push/pull
Compatibilidade: Funciona com todos os repositórios (público e privado)
Automação: Ideal para scripts e deploys, sem tokens que expiram na pior hora

O que é uma Chave SSH?

Uma chave SSH é composta por dois arquivos:

Chave privada: Fica no seu computador (NUNCA compartilhe)
Chave pública: Você adiciona no GitHub

Verificando Chaves Existentes

Antes de criar uma nova chave, vamos verificar se você já tem alguma:

ls -la ~/.ssh/

Procure por arquivos como:

id_rsa e id_rsa.pub
id_ed25519 e id_ed25519.pub

Se já existir uma chave, você pode usá-la ou criar uma nova com nome específico.

Criando uma Nova Chave SSH

Passo 1: Gerar a Chave

Execute o comando abaixo substituindo o email pelo seu:

ssh-keygen -t ed25519 -f ~/.ssh/github_2026 -C "seu-email@exemplo.com"

Parâmetros explicados:

-t ed25519: Tipo de criptografia (mais seguro que RSA)
-f ~/.ssh/github_2026: Nome do arquivo (personalize como quiser)
-C "seu-email@exemplo.com": Comentário (use seu email do GitHub)

Passo 2: Escolher uma Passphrase

O sistema perguntará se você quer uma passphrase:

Com passphrase: A chave continua protegida mesmo que alguém copie o arquivo
Sem passphrase: Qualquer pessoa com acesso ao arquivo acessa sua conta

💡 Dica: Use passphrase e deixe o ssh-agent lembrá-la por você (mostro como na seção de testes). Você digita uma única vez por sessão e o resto do dia é automático — conveniência sem abrir mão da segurança.

Passo 3: Verificar os Arquivos Criados

ls -la ~/.ssh/github_2026*

Você deve ver dois arquivos:

github_2026 (chave privada)
github_2026.pub (chave pública)

Configurando no GitHub

Passo 1: Copiar a Chave Pública

cat ~/.ssh/github_2026.pub

Copie toda a saída que começa com ssh-ed25519 e termina com seu email.

Passo 2: Adicionar no GitHub

Acesse: https://github.com/settings/ssh
Clique: “New SSH key”
Título: Digite um nome descritivo (ex: “Linux Desktop 2026”)
Key: Cole a chave pública copiada
Clique: “Add SSH key”

Passo 3: Configurar SSH Local

Edite o arquivo de configuração SSH:

nano ~/.ssh/config

Adicione esta configuração:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_2026

Testando a Configuração

Carregar a Chave no ssh-agent

O ssh-agent é um pequeno programa que guarda suas chaves destravadas em memória durante a sessão — é ele que evita digitar a passphrase a cada comando git:

# Iniciar o agent (se ainda não estiver rodando)
eval "$(ssh-agent -s)"

# Adicionar a chave (pede a passphrase uma única vez)
ssh-add ~/.ssh/github_2026

Testar Conexão SSH

ssh -T git@github.com

Resultado esperado:

Hi SEU_USUARIO! You've successfully authenticated, but GitHub does not provide shell access.

Nota: Esse comando encerra com código de saída 1 mesmo quando a autenticação funciona (o GitHub recusa o shell de propósito). Se estiver verificando $? num script, não estranhe.

Testar Clone de Repositório

git clone git@github.com:seuusuario/seurepositorio.git

Configurar Repositório Existente

Se já tem um repositório com HTTPS, mude para SSH:

git remote set-url origin git@github.com:seuusuario/seurepositorio.git

Troubleshooting

“Permission denied (publickey)”

Sintoma: SSH não consegue autenticar

Solução:

# Verificar se a chave está carregada no agent
ssh-add -l

# Se o agent não estiver rodando, inicie-o
eval "$(ssh-agent -s)"

# Adicionar a chave manualmente
ssh-add ~/.ssh/github_2026

Se o erro persistir, confirme que a chave pública foi adicionada no GitHub e que o IdentityFile no ~/.ssh/config aponta para o arquivo certo.

“WARNING: UNPROTECTED PRIVATE KEY FILE!”

Sintoma: Erro de permissões muito abertas na chave

Solução: Corrigir permissões dos arquivos (Linux/macOS):

# Chave privada (só você pode ler)
chmod 600 ~/.ssh/github_2026

# Chave pública (outros podem ler)
chmod 644 ~/.ssh/github_2026.pub

# Arquivo de configuração
chmod 600 ~/.ssh/config

“Repository not found”

Sintoma: Repositório existe mas não consegue acessar

Solução: Verificar se:

A URL do repositório está correta (usuário/nome exatos)
Você tem permissão no repositório (repositórios privados exigem convite)
A chave pública está no GitHub e o ~/.ssh/config está correto

Só tenho a chave pública (.pub) no servidor

Sintoma: Você copiou apenas o arquivo .pub para o servidor

Solução: A autenticação exige ambos os arquivos (privada E pública). A forma recomendada é criar uma chave nova direto no servidor — chave privada não foi feita para viajar entre máquinas:

# Recomendado: criar nova chave no servidor
ssh-keygen -t ed25519 -f ~/.ssh/servidor_2026 -C "seu-email@exemplo.com"
# Depois adicione a nova chave pública no GitHub

Se realmente precisar reaproveitar a mesma chave, copie a privada do computador original — mas entenda que cada máquina com essa chave é uma cópia da sua identidade:

# Último recurso: copiar a chave privada
scp ~/.ssh/github_2026 servidor:~/.ssh/

Múltiplas Contas GitHub

Sintoma: Precisa usar contas diferentes para projetos diferentes

Solução: Criar hosts específicos no ~/.ssh/config:

Host github-trabalho
    HostName github.com
    User git
    IdentityFile ~/.ssh/trabalho_key

Host github-pessoal
    HostName github.com
    User git
    IdentityFile ~/.ssh/pessoal_key

Depois use: git clone git@github-trabalho:empresa/projeto.git

Boas Práticas de Segurança

Nunca compartilhe a chave privada: O arquivo sem .pub é secreto
Use nomes descritivos: trabalho_2026, pessoal_linux etc.
Uma chave por máquina: Facilita revogar só o computador comprometido
Backup seguro: Guarde cópias das chaves em local seguro
Rotação regular: Troque as chaves a cada 1-2 anos
Revogue chaves antigas: Remova do GitHub quando não usar mais
Sempre use a chave privada no config: IdentityFile aponta para arquivo SEM .pub
Permissões corretas: Chave privada 600, pública 644, config 600

Comandos Úteis

# Remover todas as chaves do SSH agent
ssh-add -D

# Testar conexão com uma chave específica
ssh -i ~/.ssh/nome_da_chave -T git@github.com

# Ver detalhes da negociação SSH (debug)
ssh -vT git@github.com

Conclusão

Resumo do que foi configurado:

✅ Criamos uma chave SSH segura com ed25519
✅ Configuramos a chave no GitHub
✅ Testamos a autenticação SSH
✅ Aprendemos troubleshooting básico

Próximos passos: Agora você pode trabalhar com qualquer repositório GitHub sem problemas de autenticação!