Conectando no GitHub via SSH

Quando você clona um repositório no GitHub, normalmente aparecem duas opções: HTTPS e SSH.

O HTTPS funciona. Pelo menos até você trocar de máquina, o token expirar, o Git Credential Helper resolver te atrapalhar ou você simplesmente cansar de lidar com autenticação toda vez que precisa dar um push.

É aí que entra o SSH.

Com SSH, você configura uma chave na sua máquina, registra a chave pública no GitHub e pronto: sua máquina passa a provar quem é usando criptografia de chave pública. Sem digitar senha a cada operação. Sem token pessoal perdido. Sem aquela sensação de que o Git decidiu parar de funcionar do nada.

Neste artigo, vamos configurar SSH para usar com GitHub no:

• macOS

• Linux

• WSL2 no Windows

No caso do WSL2, a lógica é simples: dentro do WSL, você está usando Linux. Então o caminho é praticamente o mesmo do Linux.

Antes de criar uma chave nova, veja se você já tem uma

Muita gente já tem uma chave SSH na máquina e nem lembra.

Antes de sair criando outra, rode:

ls -la ~/.ssh

Procure por arquivos como:

id_ed25519
id_rsa

Se aparecer um arquivo desses sem .pub no final, você já tem uma chave privada criada.

Exemplo:

id_ed25519
id_ed25519.pub

Nesse caso:

• id_ed25519 é sua chave privada

• id_ed25519.pub é sua chave pública

A chave privada nunca sai da sua máquina.

A chave pública é a que você cadastra no GitHub.

Se a pasta ~/.ssh não existir, ou se ela tiver apenas arquivos como known_hosts, siga para o próximo passo.

Gerando uma chave SSH nova

Vamos usar o algoritmo Ed25519, que é o padrão moderno recomendado para esse tipo de uso. Ele gera chaves menores, rápidas e seguras para autenticação SSH.

Rode:

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

O -C adiciona um comentário à chave. Na prática, ele serve como uma etiqueta para você identificar aquela chave depois.

Use o e-mail associado à sua conta do GitHub.

Depois disso, o terminal vai perguntar onde salvar a chave:

Enter file in which to save the key (/home/seu-usuario/.ssh/id_ed25519):

Pode apertar Enter para aceitar o caminho padrão:

~/.ssh/id_ed25519

Em seguida, ele vai perguntar sobre a passphrase.

Devo usar passphrase?

A passphrase é uma senha extra que protege sua chave privada.

Pense assim: a chave privada é a “identidade” da sua máquina. Se alguém conseguir copiar essa chave e ela não tiver nenhuma proteção, essa pessoa pode tentar se autenticar como você nos serviços onde essa chave foi registrada.

A passphrase reduz esse risco.

Minha recomendação prática:

• Se você usa macOS com FileVault ativo, ou Linux com disco criptografado, deixar em branco pode ser aceitável para uso local.

• Se sua máquina não tem criptografia de disco, use uma passphrase.

• Se é uma máquina de trabalho, use passphrase.

No fim do processo, você terá dois arquivos:

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

Guarde essa regra:

id_ed25519      # chave privada: nunca compartilhe
id_ed25519.pub  # chave pública: essa vai para o GitHub

Adicionando a chave ao ssh-agent

Agora precisamos adicionar a chave ao ssh-agent.

O ssh-agent é um processo que mantém sua chave carregada em memória. Isso evita que você precise digitar a passphrase o tempo todo.

Sem ele, o SSH até funciona, mas a experiência fica bem pior.

A configuração muda um pouco entre macOS e Linux.

macOS: usando o Keychain

No macOS, o melhor caminho é integrar o SSH com o Keychain.

Crie ou edite o arquivo de configuração do SSH:

touch ~/.ssh/config

Abra esse arquivo no seu editor e adicione:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Depois, adicione a chave ao Keychain:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

A partir daqui, o macOS guarda sua passphrase no Keychain e carrega a chave automaticamente nas próximas sessões.

Linux e WSL2: subindo o agent

No Linux ou no WSL2, você pode iniciar o ssh-agent assim:

eval "$(ssh-agent -s)"

Depois adicione sua chave:

ssh-add ~/.ssh/id_ed25519

Isso resolve para a sessão atual.

O problema é que, quando você fecha o terminal, pode precisar repetir esse processo.

Para evitar isso, uma solução prática é usar o pacote keychain.

No Ubuntu, Debian ou WSL2:

sudo apt install keychain

No Arch Linux:

sudo pacman -S keychain

Depois, adicione esta linha ao seu ~/.bashrc ou ~/.zshrc:

eval "$(keychain --eval --quiet id_ed25519)"

Com isso, o keychain reaproveita o agent entre sessões e normalmente só pede sua passphrase uma vez por boot.

Copiando a chave pública

Agora você precisa copiar o conteúdo da chave pública.

No macOS:

pbcopy < ~/.ssh/id_ed25519.pub

No Linux com X11:

xclip -selection clipboard < ~/.ssh/id_ed25519.pub

No Linux com Wayland:

wl-copy < ~/.ssh/id_ed25519.pub

Se nenhum desses comandos funcionar, use o bom e velho:

cat ~/.ssh/id_ed25519.pub

Copie a saída inteira.

Ela deve começar com algo parecido com:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

De novo: copie a chave com .pub.

Nunca copie a chave privada.

Cadastrando a chave no GitHub

Agora vá até as configurações de SSH Keys no GitHub.

O caminho é:

GitHub → Settings → SSH and GPG keys → New SSH key

Preencha assim:

• Title: algo que identifique a máquina Exemplo: MacBook Pro pessoal, Desktop do trabalho, WSL2 do notebook

• Key type: Authentication Key

• Key: cole o conteúdo da sua chave pública

Depois clique em:

Add SSH key

O GitHub pode pedir sua senha ou confirmação via 2FA. Confirme e pronto.

Sua máquina agora está registrada na sua conta.

Testando a conexão com o GitHub

Antes de tentar clonar ou dar push, teste se a autenticação funcionou:

ssh -T [email protected]

Na primeira conexão, pode aparecer uma mensagem como esta:

The authenticity of host 'github.com (IP ADDRESS)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Esse fingerprint é a identidade do servidor SSH do GitHub.

A documentação oficial do GitHub publica os fingerprints esperados, e o ED25519 atual para github.com é:

SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU

Se bater, digite:

yes

A resposta esperada é algo assim:

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

Esse trecho aqui é importante:

GitHub does not provide shell access

Isso não é erro.

O GitHub está apenas dizendo que reconheceu sua chave, mas não vai abrir um terminal remoto para você. Para uso com Git, está tudo certo.

Clonando repositórios com SSH

A partir de agora, sempre que for clonar um repositório, prefira a URL SSH.

Ela tem esse formato:

[email protected]:usuario/repositorio.git

Exemplo:

git clone [email protected]:usuario/meu-projeto.git

No GitHub, clique em:

Code → SSH

Depois copie a URL.

Migrando um repositório existente de HTTPS para SSH

Se você já tem um projeto clonado via HTTPS, ele continuará usando HTTPS até você alterar a URL do remote.

Dentro da pasta do projeto, rode:

git remote -v

Se aparecer algo assim:

origin  https://github.com/usuario/repositorio.git (fetch)
origin  https://github.com/usuario/repositorio.git (push)

Troque para SSH:

git remote set-url origin [email protected]:usuario/repositorio.git

Depois confira novamente:

git remote -v

Agora deve aparecer algo assim:

origin  [email protected]:usuario/repositorio.git (fetch)
origin  [email protected]:usuario/repositorio.git (push)

Pronto. Esse repositório agora usa SSH.

Quando dá errado

Se alguma coisa quebrar, calma.

Na maioria dos casos, o problema cai em uma dessas situações.

Erro: Permission denied (publickey)

Esse é o erro clássico:

Permission denied (publickey).

Ele significa que o GitHub não conseguiu validar nenhuma chave SSH sua.

As causas mais comuns são:

1. A chave pública não foi cadastrada no GitHub.

2. A chave foi cadastrada na conta errada.

3. A chave não está carregada no ssh-agent.

4. Você cadastrou a chave privada no GitHub por engano.

Para verificar se o agent tem alguma chave carregada, rode:

ssh-add -l

Se aparecer:

The agent has no identities.

Adicione sua chave novamente:

ssh-add ~/.ssh/id_ed25519

Depois teste de novo:

ssh -T [email protected]

Erro: Could not open a connection to your authentication agent

Esse erro indica que o ssh-agent não está rodando ou não está acessível naquela sessão.

Rode:

eval "$(ssh-agent -s)"

Depois:

ssh-add ~/.ssh/id_ed25519

Se funcionar em um terminal, mas quebrar quando você abre outro, configure o keychain no Linux ou WSL2, como vimos antes.

WSL2 pedindo a chave toda hora

No WSL2, é comum o agent “sumir” entre sessões.

Você abre o terminal, adiciona a chave, tudo funciona.

Depois fecha, abre de novo e o GitHub volta a reclamar.

A solução mais simples é usar o keychain:

sudo apt install keychain

E adicionar ao ~/.bashrc ou ~/.zshrc:

eval "$(keychain --eval --quiet id_ed25519)"

Isso deixa a experiência muito mais próxima do macOS.

Um alerta importante sobre segurança

Nunca compartilhe sua chave privada.

Nunca envie por WhatsApp.

Nunca cole em ferramenta online.

Nunca suba para um repositório.

A chave privada é este arquivo:

~/.ssh/id_ed25519

A chave pública é este:

~/.ssh/id_ed25519.pub

A pública pode ir para o GitHub.

A privada fica na sua máquina.

Ponto.

Próximos passos

Com SSH funcionando, você resolveu uma parte importante do seu ambiente de desenvolvimento.

Agora dá para clonar, puxar e enviar código para o GitHub sem depender de token, senha ou cache estranho de credenciais.

Mas existem dois assuntos que merecem capítulos próprios.

O primeiro é múltiplas contas GitHub na mesma máquina.

Isso acontece quando você tem uma conta pessoal, uma conta de trabalho, ou precisa contribuir em organizações diferentes usando chaves diferentes. Nesse caso, você precisa configurar aliases no ~/.ssh/config.

O segundo é assinatura de commits com SSH.

Hoje o GitHub permite usar chaves SSH também para assinar commits e exibir o selo Verified, sem precisar configurar GPG do zero.

Mas isso fica para um próximo artigo.

Por enquanto, o mais importante está feito: seu GitHub agora fala SSH com a sua máquina.

Sem token.

Sem senha a cada push.

Sem drama.