Chave SSH do GitHub ou GitLab não funciona? A correção passo a passo

Uma chave SSH que não autentica no GitHub ou no GitLab é um dos problemas de desenvolvedor mais pesquisados no Google que existem, e metade das vezes a chave está bem — só o diagnóstico está errado. Então, antes de regenerar qualquer coisa, rode um teste e aprenda a ler a resposta dele. Depois percorra os culpados na ordem da frequência com que eles são, de fato, a causa.

“You’ve successfully authenticated, but GitHub does not provide shell access”

Se foi essa a linha que você recebeu de volta, pare — sua chave já funciona. O GitHub e o GitLab não lhe entregam um shell; eles só falam git por SSH, então autenticam você e desligam na hora, e “does not provide shell access” é eles dizendo isso, não um erro. A redação do GitLab é um pouco diferente (Welcome to GitLab, @you!), mas significa a mesma coisa. Se a sua chave funciona e, ainda assim, o git push pede senha, a chave nunca foi o problema — pule para o culpado do remote HTTPS abaixo, que é a causa real de sempre.

Passo 0: o teste que diz se há algo quebrado

Pergunte diretamente ao host git se ele reconhece a sua chave:

ssh -T git@github.com        # GitHub
ssh -T git@gitlab.com        # GitLab

Agora leia a resposta com atenção, porque a mensagem de sucesso parece um erro:

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

Isso é sucesso. “Does not provide shell access” não é uma falha — o GitHub e o GitLab não lhe dão um shell, só falam git por SSH, então autenticam você e desligam. As pessoas veem “does not provide” e começam a resolver um problema que não existe numa configuração que funciona. Se você vê seu nome de usuário naquela linha, sua chave funciona; seu problema está em outro lugar (pule para o culpado do remote HTTPS abaixo — é o problema real de sempre).

A falha de verdade, por outro lado, é assim:

git@github.com: Permission denied (publickey).

É essa que viemos corrigir. Repare no final: Permission denied (publickey) significa que o servidor não aceitou nenhuma chave que você ofereceu. Percorra a lista.

Culpado 1: a chave não foi adicionada à sua conta

A causa real mais comum. Uma chave no seu notebook não faz nada até que a metade pública dela seja registrada no host git. Copie a chave pública:

cat ~/.ssh/id_ed25519.pub     # note the .pub — this is the safe half to share

Cole isso em GitHub → Settings → SSH and GPG keys → New SSH key, ou GitLab → Preferences → SSH Keys.

Uma regra, sem exceções: cole o arquivo .pub, nunca o arquivo sem .pub. A chave pública é uma linha que começa com ssh-ed25519 AAAA… (ou ssh-rsa AAAA…). Se o que você está prestes a colar começa com -----BEGIN OPENSSH PRIVATE KEY-----, pare — essa é a sua chave privada, o segredo que é a sua identidade. Colá-la num formulário web entrega a sua credencial a qualquer um que possa ler aquela página. Compartilhe a metade pública; guarde a metade privada.

(Ainda não tem chave? Gere uma — Ed25519 em quase todos os casos (em inglês): ssh-keygen -t ed25519 -C "you@device".)

Culpado 2: a chave errada está sendo oferecida

Sua chave está registrada, mas o SSH está oferecendo uma diferente — comum quando você carrega várias chaves e o agente as tenta em uma ordem que o servidor rejeita. Veja exatamente qual chave é enviada:

ssh -vT git@github.com

Procure as linhas Offering public key:. Se a chave que você registrou não está entre elas, ou uma errada está sendo aceita, fixe a chave certa por host em ~/.ssh/config:

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

IdentitiesOnly yes é a linha-chave — ela diz ao SSH para oferecer apenas o IdentityFile que você nomeou e parar de jogar toda chave do seu agente no servidor (o que também cura o Too many authentication failures). Faça o mesmo com Host gitlab.com para o GitLab. Mais sobre como estruturar o arquivo no guia do ssh_config (em inglês).

Culpado 3: o agente não está rodando, ou a chave não está carregada

Se a sua chave tem uma frase-senha e o agente não a guarda, o SSH pode pulá-la em silêncio. Verifique o que o agente tem:

ssh-add -l

The agent has no identities (ou Could not open a connection to your authentication agent) significa que você precisa iniciá-lo e carregar a chave:

eval "$(ssh-agent -s)"        # start the agent in this shell
ssh-add ~/.ssh/id_ed25519     # load the key (prompts for the passphrase once)

ssh-add -l agora deve listar a impressão digital da sua chave. (Para entender o que o agente é e como ele guarda chaves, veja o que é o agente SSH (em inglês).)

Culpado 4: você está em um remote HTTPS, não em um SSH

Este é o culpado por trás de “minha chave funciona (o ssh -T deu certo), mas o git push ainda pede senha”. Seu repositório está configurado para usar HTTPS, que ignora as chaves SSH por completo e quer um token. Verifique:

git remote -v

Se você vê https://github.com/you/repo.git, esse é o problema — o HTTPS nunca toca na sua chave SSH. Troque o remote para SSH:

git remote set-url origin git@github.com:you/repo.git      # GitHub
git remote set-url origin git@gitlab.com:you/repo.git      # GitLab

Rode git remote -v de novo para confirmar que agora começa com git@. Essa única correção resolve uma enorme parcela dos relatos de “chave SSH não funciona” em que a chave estava bem o tempo todo.

Culpado 5: permissões em ~/.ssh

O SSH se recusa a usar chaves e config que outros poderiam adulterar. Se a saída detalhada menciona modos ruins, ou as chaves estão sendo ignoradas sem motivo claro:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519          # private key
chmod 644 ~/.ssh/id_ed25519.pub      # public key
chmod 600 ~/.ssh/config

No Windows, isso aparece depois de copiar chaves de um drive sincronizado ou entre máquinas; corrija pelas propriedades de Segurança do arquivo, ou mantenha as chaves fora de pastas sincronizadas com a nuvem.

Culpado 6: pedidos de frase-senha toda vez

Se toda operação de git exige a frase-senha da sua chave, o agente não está guardando em cache. Carregue-a uma vez com ssh-add (em inglês) (culpado 3) e faça com que ela persista entre sessões adicionando ao ~/.ssh/config:

Host github.com gitlab.com
    AddKeysToAgent yes

No macOS, ssh-add --apple-use-keychain ~/.ssh/id_ed25519 armazena a frase-senha no Keychain para que ela sobreviva a reinicializações.

Culpado 7: duas contas, um host

Contas do GitHub de trabalho e pessoal não podem compartilhar uma chave — uma dada chave pública pertence a exatamente uma conta. Dê a cada uma a sua própria chave e um alias Host que a seleciona:

Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/work_ed25519
    IdentitiesOnly yes

Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/personal_ed25519
    IdentitiesOnly yes

Depois clone ou defina o remote com o alias como host: git@github-work:org/repo.git. O SSH casa github-work, escolhe a chave de trabalho e reescreve a conexão para github.com por baixo dos panos.

Culpado 8: SSO da organização não autorizado (GitHub)

Você autentica bem nos seus próprios repositórios, mas recebe Permission denied nos repositórios de uma organização por trás de SAML SSO. A chave existe, mas não está autorizada para aquela organização. Vá em Settings → SSH and GPG keys, encontre a chave, clique em Configure SSO e autorize-a para a organização. O GitLab tem um caso paralelo em que uma chave expirada é rejeitada em silêncio — verifique a data de expiração da chave em SSH Keys se uma chave que antes funcionava parar de repente.

Quando ainda é Permission denied (publickey)

Se você percorreu a lista e ainda esbarra no mesmo erro, você restringiu a um problema genuíno de aceitação de chave — o ciclo sistemático para esse erro exato (ler ssh -vvv, a lista de métodos do servidor, chaves oferecidas vs. aceitas) está em permission denied (publickey), uma correção sistemática e rápida (em inglês), e o mapa mais amplo dos erros de SSH está em erros de SSH decifrados. Mas, para hosts git especificamente, a ordem acima pega quase tudo: registre a chave pública, ofereça a certa, carregue-a no agente e certifique-se de que você está mesmo em um remote SSH.

Onde um cliente elimina a configuração por completo

Boa parte desse atrito é burocracia — qual chave pertence a qual host, se ela está carregada, se o remote é mesmo SSH. O Termalin mantém a chave junto do host a que ela pertence, desbloqueia suas chaves uma vez por meio de um agente integrado para que as frases-senha não sejam redigitadas (e um pedido cancelado nunca pula uma chave em silêncio) e — porque fala o protocolo padrão do ssh-agent — o git e a sua CLI podem assinar por esse mesmo agente. As impressões digitais ficam visíveis por chave, então registrar a metade pública certa no GitHub ou no GitLab é copiar e colar, não uma caça por cinco pastas ~/.ssh. O malabarismo de contas e aliases acima vira uma configuração por host, em vez de um quebra-cabeça de arquivo de config.

---

O Termalin é um cliente SSH gratuito e multiplataforma que gerencia suas chaves com um agente de desbloqueio único pelo qual o git pode assinar — baixe o Termalin, ou leia como ele lida com as chaves com segurança.