Como criar uma chave SSH no GitHub e usar no VS Code

Usar SSH no GitHub é uma forma prática de autenticar operações do Git sem depender de senha ou token a cada envio. Você cria um par de chaves no computador, cadastra apenas a chave pública no GitHub e mantém a privada protegida.

Neste guia, mostro o caminho completo para Linux, macOS e Windows: geração da chave, carregamento no agente SSH, cadastro no GitHub, teste da conexão e uso do endereço SSH no VS Code.

O que é uma chave SSH do GitHub?

SSH é um protocolo que cria um canal seguro para comunicação em uma rede que, por si só, não é confiável. No GitHub, a autenticação usa duas partes: a chave privada, guardada no seu computador, e a chave pública, cadastrada na sua conta.

É parecido com uma fechadura: você publica a fechadura, mas mantém a chave. A chave privada nunca deve ser enviada por e-mail, anexada a um chamado ou colocada no repositório.

Antes de começar

• Tenha uma conta no GitHub e o Git instalado.
• Abra o Terminal no macOS ou Linux, ou o Git Bash/PowerShell no Windows.
• Confira se você já possui uma chave em ~/.ssh. Se já existir uma, não a sobrescreva sem verificar onde ela é usada.

Para listar arquivos SSH existentes, use:

ls -la ~/.ssh

No PowerShell, o equivalente é:

Get-ChildItem $HOME\.ssh

Como criar a chave SSH

O GitHub recomenda o algoritmo Ed25519 para uma nova chave. Troque o endereço pelo e-mail associado à sua conta:

ssh-keygen -t ed25519 -C "seu-email@exemplo.com"

Quando o programa perguntar onde salvar, pressione Enter para aceitar o caminho padrão, desde que ele não substitua uma chave que você ainda usa. Depois, defina uma frase secreta (passphrase). Ela adiciona uma camada de proteção se alguém conseguir copiar o arquivo privado.

Em um sistema antigo sem suporte a Ed25519, a documentação do GitHub indica esta alternativa:

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

Não use ssh-rsa por hábito em máquinas atuais: chaves DSA novas não são aceitas pelo GitHub, e clientes antigos podem precisar de atualização para trabalhar com as assinaturas SHA-2 de chaves RSA.

Como carregar a chave no ssh-agent

O ssh-agent é um processo que guarda a chave desbloqueada durante a sessão. Assim, você não precisa digitar a passphrase em todas as operações.

Linux e macOS

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

No macOS, o GitHub orienta configurar o arquivo ~/.ssh/config para integrar a chave ao Keychain. Um exemplo é:

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

Se você não usa passphrase, retire a linha UseKeychain yes. No Linux, essa opção específica do macOS não deve ser adicionada.

Windows

Abra o PowerShell como administrador uma vez para configurar e iniciar o serviço:

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

Depois, em um terminal comum, carregue a chave:

ssh-add $HOME\.ssh\id_ed25519

Se o Windows usar o ssh.exe embutido no Git para Windows e não encontrar a chave carregada no agente nativo, o GitHub sugere apontar o Git para o OpenSSH do sistema:

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

Como adicionar a chave pública ao GitHub

Agora copie o conteúdo do arquivo público. O arquivo termina em .pub; o arquivo sem essa extensão é a sua chave privada e não deve ser copiado.

No Linux ou macOS, você pode exibir a chave com:

cat ~/.ssh/id_ed25519.pub

No PowerShell:

Get-Content $HOME\.ssh\id_ed25519.pub

Copie a linha inteira, sem inserir quebras ou espaços extras. No GitHub, abra sua foto de perfil e siga este caminho:

1. Settings;
2. SSH and GPG keys;
3. New SSH key;
4. escolha um título que identifique o aparelho, como “Notebook pessoal”;
5. selecione Authentication key;
6. cole a chave pública e clique em Add SSH key.

O título não altera a segurança da chave, mas ajuda a revogá-la depois. Se você perder o computador, remova a chave correspondente da conta.

Como testar a conexão com o GitHub

No terminal, execute:

ssh -T git@github.com

Na primeira conexão, o SSH pode perguntar se você confia na impressão digital do servidor. Compare-a com a lista oficial de fingerprints do GitHub antes de responder yes.

Quando tudo estiver certo, o GitHub informará que você foi autenticado, mas que o serviço não oferece acesso a um shell. Essa mensagem é normal. O comando de teste pode terminar com código 1 mesmo assim, porque ele não abre um terminal remoto.

Se aparecer Permission denied (publickey), confira nesta ordem:

• se a chave pública cadastrada é a mesma saída de ~/.ssh/id_ed25519.pub;
• se a chave privada foi carregada com ssh-add -l;
• se você está usando a conta do GitHub correta;
• se o nome do arquivo é diferente de id_ed25519 e precisa ser informado em ~/.ssh/config;
• se o repositório pertence a uma organização que exige autorização de SSO.

Como usar SSH no VS Code

Com a autenticação funcionando, copie o endereço SSH do repositório no GitHub. Ele segue este formato:

git@github.com:usuario/nome-do-repositorio.git

No VS Code, abra a paleta de comandos com Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS, escolha Git: Clone, cole o endereço SSH e selecione a pasta de destino. Também é possível abrir a área Source Control e escolher Clone Repository.

Depois de abrir a pasta, faça uma alteração pequena e use a área Source Control para revisar, preparar e confirmar o commit. Se quiser entender como proteger configurações do projeto, veja também o guia do JSMS sobre variáveis de ambiente no Node.js.

SSH ou HTTPS: qual escolher?

Critério	SSH	HTTPS
Configuração inicial	Exige criar e cadastrar uma chave	Começa mais rápido no navegador
Uso frequente	Fica confortável depois do primeiro ajuste	Pode pedir autenticação conforme o gerenciador de credenciais
Segurança	Depende da proteção da chave privada e da passphrase	Depende do token e do armazenamento seguro das credenciais
Ambientes corporativos	Pode exigir aprovação de SSO	Pode funcionar melhor onde a rede bloqueia SSH

Para quem trabalha diariamente com repositórios, SSH costuma valer o esforço inicial. Em uma rede que bloqueia a porta usada pelo SSH ou em um computador compartilhado, HTTPS pode ser mais simples. O importante é não guardar senha, token ou chave privada no código.

Conclusão

A configuração se resume a quatro ideias: gerar o par de chaves, proteger e carregar a privada, cadastrar a pública no GitHub e testar com ssh -T git@github.com. Depois disso, o VS Code consegue clonar e sincronizar repositórios usando o endereço SSH.