# Permission denied (publickey) ao clonar repositório no cPanel

A cadeia completa, do par de chaves no SSH Access ao ssh -T que confirma a autenticação, com verificação em cada etapa e tabela de diagnóstico por sintoma.

> o erro aparece porque a URL do clone está em HTTPS ou porque a chave do servidor nunca foi registrada como deploy key. A correção é gerar um par ed25519 no SSH Access, autorizá-lo, registrar a pública como deploy key read-only, aceitar a fingerprint do host e validar com ssh -T antes de clonar.

João Rizzon · 2026-10-08 · Painéis

---

## O que o servidor está dizendo quando recusa a publickey

Quando o `git clone` dentro da conta cPanel devolve:

```
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
```

o servidor remoto encerrou a autenticação SSH porque nenhuma das chaves públicas oferecidas pelo cliente foi aceita. Não é erro de permissão de arquivo no `home`, não é repositório inexistente e não é problema de rede: a conexão TCP abriu, o handshake SSH começou e o método `publickey` falhou.

Na prática, dentro de uma conta cPanel, isso cai quase sempre em uma de três situações:

- A URL do repositório é HTTPS (`https://github.com/user/repo.git`), e o Git Version Control do cPanel não tem como fornecer senha ou token interativamente em um repositório privado.
- Existe um par de chaves no `~/.ssh`, mas a chave pública nunca foi registrada no provedor como deploy key.
- A chave foi registrada, mas o host remoto ainda não está no `~/.ssh/known_hosts` e o clone não-interativo falha antes de chegar à autenticação, ou o par foi gerado fora do SSH Access e não está autorizado.

A documentação do cPanel trata essa cadeia inteira no [Guide to Git - Set up Access to Private Repositories](https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-set-up-access-to-private-repositories/). O que segue organiza esse procedimento na ordem em que ele realmente precisa ser executado, com verificação em cada etapa.

## As sete etapas na ordem em que precisam ser executadas

A sequência importa porque cada passo depende do anterior. Pular a validação intermediária é o que faz o erro reaparecer no final sem pista de onde veio.

| Etapa | Onde executa | Como verificar que deu certo |
|---|---|---||
| 1. Gerar o par de chaves | cPanel › SSH Access › Manage SSH Keys | A chave aparece listada como private/public |
| 2. Autorizar a chave na conta | SSH Access › Manage | Status muda para `authorized` |
| 3. Copiar a chave pública | SSH Access › View/Download | Texto começa com `ssh-ed25519 AAAA...` |
| 4. Registrar como deploy key | GitHub / GitLab / Bitbucket | Chave listada no repositório, read-only |
| 5. Aceitar a fingerprint do host | Terminal SSH da conta | Linha correspondente em `~/.ssh/known_hosts` |
| 6. Validar a autenticação | `ssh -T git@github.com` | Mensagem de boas-vindas do provedor |
| 7. Clonar | Git Version Control ou `git clone` | Diretório criado com `.git` |

## Gerar o par ed25519 no SSH Access e autorizá-lo

Gere o par pelo próprio cPanel, em **SSH Access › Manage SSH Keys › Generate a New Key**. O motivo não é estético: a chave gerada ali já nasce no `~/.ssh` da conta, com dono e modo corretos, e o painel oferece o botão de autorização.

Escolha **ed25519** quando o campo de tipo estiver disponível. A chave é curta, o handshake é rápido e os três provedores principais aceitam. Se o formulário só oferecer RSA, use RSA com 4096 bits.

Deixe a passphrase vazia. Uma deploy key com passphrase exige um agente SSH carregado no momento do clone, e o Git Version Control do cPanel roda sem sessão interativa. A compensação de risco é o passo 4: a chave entra no provedor como **somente leitura** e vinculada a um único repositório.

Depois de gerar, clique em **Manage** ao lado da chave privada e confirme a autorização. Uma chave listada mas não autorizada continua produzindo `Permission denied (publickey)`.

### Conferir nome e permissões da chave pelo terminal

Se você tem acesso SSH à conta, confira antes de prosseguir. O nome do arquivo é o que você digitou em **Key Name** na hora de gerar (o cPanel sugere `id_rsa`, independente do tipo escolhido), então liste o diretório inteiro em vez de chutar o nome:

```bash
ls -l ~/.ssh/
stat -c '%a %n' ~/.ssh ~/.ssh/*
```

Se preferir checar um par específico, troque `id_minhachave` pelo nome que aparece no cPanel:

```bash
stat -c '%a %n' ~/.ssh/id_minhachave ~/.ssh/id_minhachave.pub
```

O esperado é `700` no diretório `~/.ssh`, `600` em cada chave privada e `644` nas públicas. Um `No such file or directory` aqui quase sempre significa que o arquivo tem outro nome, não que a chave sumiu: confira a coluna de nome em SSH Access › Manage SSH Keys. Permissão frouxa na chave privada faz o cliente OpenSSH recusar usá-la, e a mensagem resultante é exatamente a mesma do título deste artigo.

## Registrar a chave pública como deploy key somente leitura

Copie o conteúdo da chave **pública** (a que termina em `.pub`). No cPanel, use **View/Download** ao lado da chave pública e copie o bloco inteiro, de `ssh-ed25519` até o comentário final, em uma linha só.

Os caminhos nos provedores:

- **GitHub**: repositório › Settings › Deploy keys › Add deploy key. Deixe **Allow write access** desmarcado.
- **GitLab**: repositório › Settings › Repository › Deploy keys. Não conceda `write access to repository`.
- **Bitbucket**: repositório › Repository settings › Access keys. As access keys do Bitbucket são read-only por definição.

Use deploy key por repositório em vez de adicionar a chave à sua conta pessoal de usuário. Uma chave na conta de usuário dá ao servidor de hospedagem o mesmo alcance que você tem em todos os seus repositórios privados. Uma deploy key read-only dá acesso de leitura a um repositório e nada mais. Se a conta cPanel for comprometida, o raio de dano é outro.

Uma deploy key não pode ser reaproveitada em dois repositórios do mesmo provedor no GitHub. Se você precisa clonar dois repositórios privados na mesma conta, gere um par por repositório e diferencie por host alias no `~/.ssh/config`.

## Trocar a URL HTTPS pelo formato git@host:usuario/repo.git

O Git Version Control do cPanel só consegue autenticar em repositório privado por SSH. A URL precisa estar no formato `git@host:usuario/repo.git`.

| Provedor | HTTPS (não funciona em privado) | SSH (use este) |
|---|---|---||
| GitHub | `https://github.com/acme/app.git` | `git@github.com:acme/app.git` |
| GitLab | `https://gitlab.com/acme/app.git` | `git@gitlab.com:acme/app.git` |
| Bitbucket | `https://bitbucket.org/acme/app.git` | `git@bitbucket.org:acme/app.git` |

Os nomes `acme/app` acima são exemplo fictício: substitua pelo seu namespace e repositório reais.

Se o repositório já existe na conta e só a URL está errada, corrija sem recriar nada:

```bash
cd ~/repositories/app
git remote -v
git remote set-url origin git@github.com:acme/app.git
git remote -v
```

Depois de trocar a URL, rode `git fetch` uma vez para confirmar que o remoto responde.

## Aceitar a fingerprint do host e confirmar com ssh -T

Esta é a etapa mais pulada e a que produz falha silenciosa em processo automatizado. O OpenSSH recusa conectar a um host desconhecido quando não há como perguntar ao usuário. Resolva abrindo uma sessão SSH na conta cPanel e executando o teste de autenticação:

```bash
ssh -T git@github.com
```

Na primeira vez, o cliente mostra a fingerprint do host e pergunta se você confia. Compare a fingerprint exibida com a publicada pelo próprio provedor na documentação de chaves de host dele antes de responder `yes`. Aceitar sem conferir é aceitar qualquer coisa que esteja respondendo naquele IP.

Aceito o host, a resposta esperada do GitHub é uma linha confirmando o nome de usuário e dizendo que o acesso shell não é permitido. Isso é sucesso: autenticou por chave e o servidor recusou shell, que é o comportamento correto. GitLab e Bitbucket devolvem mensagens equivalentes.

Se `ssh -T` ainda devolver `Permission denied (publickey)`, o problema está na chave, não na URL nem no host. Use o modo verboso para ver qual chave foi oferecida:

```bash
ssh -vT git@github.com
```

Procure as linhas `Offering public key:` e `Authentications that can continue:`. Se nenhuma chave foi oferecida, o arquivo privado não está em `~/.ssh` com nome padrão, ou o `~/.ssh/config` aponta para outro caminho. Se a chave foi oferecida e recusada, a pública que está no provedor não corresponde a essa privada: recopie do cPanel e cole de novo, conferindo que não entrou quebra de linha no meio.

### Um par de chaves por repositório com alias no ~/.ssh/config

Com um par por repositório, crie `~/.ssh/config` com aliases:

```
Host github-app
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_app
  IdentitiesOnly yes
```

O caminho em `IdentityFile` tem de bater com o nome que você informou em **Key Name** no cPanel, não com um nome padrão presumido.

E use a URL `git@github-app:acme/app.git`. O `IdentitiesOnly yes` impede que o cliente ofereça todas as chaves do diretório, o que evita estourar o limite de tentativas do servidor antes de chegar à chave certa.

## Clonar pelo Git Version Control sem expor o .git na web

Com `ssh -T` respondendo, vá em **cPanel › Git Version Control › Create**, marque **Clone a Repository**, cole a URL no formato SSH e informe o caminho de destino dentro do `home`.

Mantenha o repositório fora do `public_html`. Um clone dentro do docroot expõe o diretório `.git` à web, e o conteúdo de `.git/config` e do histórico vira leitura pública. O padrão razoável é clonar em `~/repositories/nome` e publicar a partir dali, por `.cpanel.yml` ou por processo próprio.

Se preferir a linha de comando, o equivalente é:

```bash
mkdir -p ~/repositories
cd ~/repositories
git clone git@github.com:acme/app.git
```

## Qual etapa refazer para cada sintoma

| Sintoma | Causa provável | Ação |
|---|---|---||
| `Permission denied (publickey)` no clone e no `ssh -T` | Chave não autorizada no cPanel ou não registrada no provedor | Refazer etapas 2 a 4 |
| `ssh -T` funciona, clone falha | URL ainda em HTTPS | `git remote set-url` para o formato `git@` |
| `Host key verification failed` | Host ausente do `known_hosts` | Rodar `ssh -T` interativo e aceitar após conferir a fingerprint |
| `repository not found` autenticando ok | Deploy key em outro repositório, ou namespace errado na URL | Conferir em qual repositório a chave está registrada |
| Funciona no shell, falha no painel | Chave com passphrase, sem agente na sessão do painel | Regerar o par sem passphrase |
| `Too many authentication failures` | Muitas chaves oferecidas antes da correta | `IdentitiesOnly yes` no `~/.ssh/config` |

## Como remover o acesso quando o deploy sai de uso

Remover o acesso é mais simples do que concedê-lo, e vale fazer quando o site sai do ar, muda de servidor ou troca de dono.

- Apague a deploy key no provedor. Isso corta o acesso imediatamente, independente do que ainda exista no servidor.
- Remova o par de chaves em **SSH Access › Manage SSH Keys › Delete**.
- Se houver entradas obsoletas, limpe o `known_hosts` com `ssh-keygen -R github.com`. O arquivo é recriado na próxima conexão aceita.

Uma observação contra o interesse de quem vende hospedagem: se o repositório for público, nada disso é necessário. Clone por HTTPS, sem chave nenhuma, e você elimina toda essa superfície de configuração. A cadeia de deploy key só existe porque o repositório é privado.

Fonte do procedimento: documentação oficial do cPanel, [Guide to Git - Set up Access to Private Repositories](https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-set-up-access-to-private-repositories/), consultada em 07/10/2026. Os nomes de repositório usados nos comandos são exemplos fictícios.

