No cenário atual de desenvolvimento de software e cultura DevOps, a segurança é um dos pilares fundamentais. Quando falamos em integrar sistemas de CI/CD (Integração Contínua e Entrega Contínua), automatizar deploys ou permitir que servidores acessem repositórios privados, a gestão de credenciais torna-se um desafio crítico. Utilizar senhas simples é uma prática obsoleta e perigosa.
Neste guia técnico, exploraremos as duas formas mais seguras e profissionais de autenticar acessos ao GitHub: as Deployment Keys (Chaves de Deploy) e os Fine-grained Personal Access Tokens (Tokens de Acesso Pessoais de Grão Fino). Ao final desta leitura, você saberá exatamente qual método escolher para o seu projeto e como configurá-los passo a passo.
Introdução#
A autenticação no GitHub evoluiu para seguir o “Princípio do Menor Privilégio” (PoLP). Isso significa que uma credencial não deve ter mais acesso do que o estritamente necessário para realizar sua função.
Existem dois caminhos principais para automação:
- Deployment Keys: São chaves SSH associadas a um repositório específico. Elas são ideais para servidores de produção ou máquinas de deploy que precisam apenas “ler” ou “escrever” no código de um projeto específico.
- Fine-grained Personal Access Tokens (PATs): São tokens baseados em usuários que permitem um controle granular sobre quais repositórios, organizações e permissões (leitura, escrita, administração) podem ser acessados. São ideais para ferramentas de terceiros (como Vercel, Netlify ou Jenkins) e scripts de automação de alto nível.
Pré-requisitos#
Antes de começar, certifique-se de que você possui:
- Uma conta ativa no GitHub.
- O Git instalado em sua máquina local.
- Acesso de administrador ou permissões de escrita no repositório desejado.
- Um terminal (Linux, macOS ou Windows com PowerShell/Git Bash).
- Conhecimento básico de comandos de terminal.
Método 1: Configurando Deployment Keys (Chaves de Deploy)#
As Deployment Keys são chaves SSH que funcionam como “identidades” para servidores. Diferente das chaves SSH padrão de usuários, elas são vinculadas a um repositório, não a uma conta pessoal.
Por que usar Deployment Keys?
- Isolamento: Se a chave for comprometida, apenas aquele repositório está em risco.
- Segurança de Servidor: O servidor de deploy não precisa de acesso a nenhum outro projeto da sua conta.
- Privacidade: Não expõe informações da sua conta pessoal.
Passo a Passo para Criação
1. Gerar o par de chaves SSH
No terminal do seu servidor ou máquina local, execute o comando abaixo para gerar uma nova chave. Substitua o e-mail pelo seu e-mail do GitHub (opcional, mas recomendado).
ssh-keygen -t ed25519 -C "deploy_key_projeto_x"
Nota: O algoritmo ED25519 é mais seguro e rápido que o RSA tradicional.
Quando o sistema perguntar onde salvar a chave, você pode pressionar Enter para o padrão ou definir um caminho específico. Quando pedir uma senha (passphrase), você pode deixar em branco para automação total ou definir uma senha para maior segurança.
2. Adicionar a chave pública ao GitHub
Após a geração, você terá dois arquivos (geralmente em ~/.ssh/):
id_ed25519(Chave privada – NUNCA compartilhe)id_ed25519.pub(Chave pública – Esta é a que vamos usar)
Exiba o conteúdo da chave pública:
cat ~/.ssh/id_ed25519.pub
Copie todo o conteúdo que começa com ssh-ed25519... e termine com o seu e-mail.
3. Configurar no Repositório
- Vá até o seu repositório no GitHub.
- Clique em Settings (Configurações) no menu superior.
- No menu lateral esquerdo, procure por Deploy keys.
- Clique no botão Add deploy key.
- Cole a chave pública no campo correspondente.
- Dê um título (ex: “Servidor de Produção”).
- Importante: Marque a opção “Allow write access” apenas se o seu servidor precisar enviar código (fazer
git push) para o repositório. Para apenas baixar o código, deixe desmarcado. - Clique em Add key.
4. Testar a conexão
No servidor, adicione a chave privada ao agente SSH ou ao arquivo authorized_keys:
ssh -T [email protected]
Se tudo estiver correto, você verá uma mensagem de autenticação bem-sucedida.
Método 2: Fine-grained Personal Access Tokens (PATs)#
Os tokens de acesso pessoal “Fine-grained” são a nova geração de tokens do GitHub. Eles substituem os tokens “Classic” por oferecerem um controle muito mais detalhado sobre o que o token pode fazer.
Por que usar Fine-grained PATs?
- Escopo Limitado: Você pode definir que o token só pode ler arquivos, mas não deletar tags.
- Expiração Controlada: Você pode definir prazos curtos para o token, aumentando a segurança.
- Acesso a Organizações: Permite acesso seletivo a repositórios específicos dentro de uma organização empresarial.
Passo a Passo para Criação
1. Acessar a área de Tokens
- No GitHub, clique na sua foto de perfil no canto superior direito e vá em Settings.
- No menu lateral, role até o fim e clique em Developer settings.
- No menu à esquerda, clique em Personal access tokens e selecione Fine-grained tokens.
- Clique em Generate new token.
2. Configurar o Token
- Token name: Dê um nome descritivo (ex: “CI_Pipeline_Projeto_X”).
- Expiration: Escolha um período de validade (ex: 90 dias). Recomenda-se não deixar sem data de expiração.
- Description: Explique para que este token será usado.
3. Definir Permissões (Scopes)
Aqui é onde o “Fine-grained” brilha. Você deve selecionar:
- Repository access: Escolha “Only select repositories” e selecione o projeto desejado.
- Permissions:
– Contents: Geralmente “Read-only” para deploys ou “Read and write” para automações que criam releases.
– Metadata: Geralmente “Read-only” (obrigatório).
– Actions: Se você for usar para disparar workflows.
4. Finalizar e Copiar
Clique em Generate token.
Atenção: Copie o token imediatamente e salve-o em um gerenciador de segredos (como HashiCorp Vault, AWS Secrets Manager ou variáveis de ambiente do seu CI/CD). Você não conseguirá vê-lo novamente.
5. Uso via HTTPS
Para usar este token no terminal ou em um script, você o utiliza no lugar da senha quando o Git solicitar autenticação:
git clone https://@github.com/usuario/repositorio.git
Comparativo: Deployment Keys vs. Fine-grained Tokens#
Para ajudar na sua decisão técnica, veja esta tabela comparativa:
| Característica | Deployment Keys | Fine-grained Tokens (PAT) |
|---|---|---|
| Tipo de Autenticação | SSH | HTTPS |
| Escopo de Acesso | Vinculado a um Repositório Único | Múltiplos Repositórios (Seletivo) |
| Identidade | Identidade de Máquina/Servidor | Identidade de Usuário/Aplicação |
| Facilidade de Uso | Melhor para servidores fixos | Melhor para APIs e ferramentas de terceiros |
| Gestão de Expiração | Manual (Troca de chaves) | Automática (Configuração de data) |
| Segurança | Alta (Isolamento total) | Alta (Controle granular de permissão) |
Dicas de Segurança e Melhores Práticas#
Para manter seus repositórios seguros, siga estas diretrizes recomendadas pela comunidade de segurança da informação:
- Nunca faça Hardcode: Nunca coloque chaves ou tokens diretamente no código-fonte (ex: em arquivos
.envque são commitados). Use variáveis de ambiente. - Rotação de Credenciais: Troque suas chaves e tokens periodicamente. Tokens com expiração curta são uma excelente prática para reduzir a janela de ataque.
- Use o Princípio do Menor Privilégio: Se a sua ferramenta de deploy só precisa baixar o código, não dê permissão de escrita.
- Monitoramento: O GitHub fornece logs de auditoria. Verifique periodicamente se houve acessos inesperados usando suas chaves ou tokens.
- Proteja o arquivo
.ssh: No servidor, garanta que apenas o usuário do sistema necessário tenha permissão de leitura na pasta.ssh.
FAQ – Perguntas Frequentes#
1. Posso usar a mesma Deployment Key em vários repositórios?
Sim, mas isso viola o princípio de segurança. O ideal é que cada repositório tenha sua própria chave de deploy para garantir o isolamento.
2. Qual a diferença entre Token Classic e Fine-grained?
O Token Classic dá acesso a todas as suas permissões de usuário de uma vez (ou um grupo amplo). O Fine-grained permite que você escolha exatamente quais repositórios e quais ações (leitura, escrita, etc.) o token pode realizar.
3. Como remover uma chave de deploy se ela for vazada?
Vá até as configurações do repositório, na seção “Deploy keys”, e remova a chave. Em seguida, gere um novo par de chaves e atualize o servidor.
4. O que acontece se o token expirar?
As automações que utilizam o token (como o Jenkins ou GitHub Actions) falharão com erro de autenticação (401 Unauthorized). Você precisará gerar um novo token e atualizar a variável de ambiente.
Conclusão#
A segurança no GitHub não é um destino, mas um processo contínuo. Escolher entre Deployment Keys e Fine-grained Tokens depende inteiramente do seu fluxo de trabalho: utilize chaves SSH para servidores de infraestrutura e tokens para integrações de software e ferramentas de terceiros.
Ao seguir os passos descritos neste guia, você garante que seu fluxo de trabalho esteja alinhado com as melhores práticas de mercado, protegendo seu código contra acessos não autorizados e facilitando uma automação robusta e escalável.
Fontes consultadas: Documentação Oficial do GitHub (GitHub Docs) sobre SSH Keys e Personal Access Tokens.




