Como criar e usar uma chave SSH no Windows, no Linux e no macOS

Digitar usuário e token a cada git push cansa, e colar token em arquivo de texto para não esquecer é pior. A chave SSH resolve as duas coisas: você gera um par de chaves uma vez, entrega a parte pública ao GitHub (ou ao servidor), e a conexão passa a ser autenticada pela chave que fica no seu computador.

O processo é quase igual nos três sistemas. O que muda é o jeito de deixar a chave carregada, para não digitar a senha dela toda hora.

Gere o par de chaves

Abra o terminal (no Windows, o PowerShell ou o Git Bash) e rode o comando que a documentação do GitHub recomenda, com o e-mail da sua conta:

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

O Ed25519 é o tipo indicado hoje. Se o sistema for antigo e não aceitar, a alternativa da própria documentação é uma chave RSA de 4096 bits:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

O programa pergunta onde salvar. Aceite o padrão com Enter: a chave vai para a pasta .ssh do seu usuário, com o nome id_ed25519. Se já existir uma chave com esse nome, escolha outro, ou você sobrescreve a antiga.

Depois ele pede uma passphrase, a senha da chave. Dá para deixar em branco, mas não deixe. Sem ela, quem copiar o arquivo da chave copia o seu acesso junto. Com ela, o arquivo sozinho não basta.

No fim, você tem dois arquivos: id_ed25519, a chave privada, que nunca sai do seu computador, e id_ed25519.pub, a pública, que é a que você entrega.

Deixe a chave no ssh-agent

O ssh-agent guarda a chave já destravada enquanto você trabalha, e é ele que evita digitar a passphrase a cada comando.

No Windows, abra o PowerShell como administrador e ligue o serviço:

Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

Depois, num terminal comum, adicione a chave:

ssh-add c:/Users/SEU_USUARIO/.ssh/id_ed25519

No Linux, inicie o agente e adicione a chave:

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

No macOS, dá para guardar a passphrase no Keychain e esquecer dela. Crie ou edite o arquivo ~/.ssh/config com:

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

E adicione a chave avisando que é para usar o Keychain:

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

Se você não pôs passphrase, tire a linha UseKeychain e a opção --apple-use-keychain.

Entregue a chave pública e teste

Abra o arquivo id_ed25519.pub, copie o conteúdo inteiro (é uma linha só, começando com ssh-ed25519) e cole no GitHub, em Settings, SSH and GPG keys, New SSH key. Num servidor Linux, a mesma linha vai no arquivo ~/.ssh/authorized_keys do usuário de destino.

Para confirmar que funcionou, o teste do GitHub é um comando só:

ssh -T [email protected]

Na primeira vez, o SSH pergunta se você confia no servidor. Confira a impressão digital com a publicada pelo GitHub e responda “yes”. A resposta certa é uma saudação com o seu nome de usuário, avisando que o GitHub não oferece acesso a shell. Ela não é erro: a autenticação passou.

O que costuma dar errado

O tropeço mais comum é o repositório continuar pedindo senha depois de tudo pronto. Quase sempre ele foi clonado por HTTPS. Confira com git remote -v: se o endereço começa com https://, troque pelo endereço SSH, que começa com [email protected]:, usando git remote set-url origin.

O outro é copiar o arquivo errado. A chave que vai para o GitHub é sempre a que termina em .pub. Se você colou a privada em algum lugar, considere a chave comprometida: apague o par, gere outro e remova a antiga da conta.

E um hábito que economiza dor de cabeça: uma chave por computador, com um nome que diga qual é (“notebook do trabalho”, “desktop de casa”). Quando um aparelho some, você revoga só a chave dele.

Fontes: GitHub Docs: gerar uma chave SSH, GitHub Docs: testar a conexão SSH

Produzido com auxílio de IA e revisado pela redação.