Decent Newsroom
Sign In

Como usar uma chave GPG como chave SSH (e integrar tudo ao Git)

By OK3E October 21, 2026 · Edited October 21, 2026
Um guia prático e amigável para proteger arquivos, autenticar-se em servidores e assinar commits.

Atualizado em: 21 de outubro de 2026 · Público: iniciantes e pessoas que já usam terminal · Exemplos principais: Linux e macOS

Se você usa GitHub, GitLab ou acessa servidores Linux, provavelmente já ouviu falar em SSH. Se também quer comprovar que determinado commit foi realmente assinado pela sua chave, talvez já tenha encontrado GPG. A boa notícia é que essas tecnologias podem trabalhar juntas — sem precisar criar uma identidade criptográfica completamente independente para cada finalidade.

Neste artigo, vamos criar uma identidade GPG, adicionar subchaves específicas, configurar o gpg-agent para apresentar uma delas como chave SSH e integrar a assinatura digital ao Git. Também veremos como criptografar arquivos e resolver problemas comuns.

Antes de começar: o tutorial não transforma uma chave pública GPG comum em uma chave privada SSH. A estratégia correta é usar uma subchave OpenPGP com capacidade de autenticação, disponibilizada ao OpenSSH pelo gpg-agent.

Sumário

  1. O que são PGP, OpenPGP, GPG e SSH?
  2. Por que usar GPG no dia a dia?
  3. Entendendo chaves e subchaves
  4. Instalando as ferramentas
  5. Criando uma identidade GPG
  6. Configurando o GPG como agente SSH
  7. Usando a chave no GitHub e em servidores
  8. Assinando commits e tags do Git
  9. Criptografando e assinando arquivos
  10. Backup, revogação e segurança
  11. Solução de problemas
  12. Perguntas frequentes
  13. Referências e documentação oficial

1. O que são PGP, OpenPGP, GPG e SSH?

Esses nomes aparecem juntos, mas não significam a mesma coisa:

Termo O que significa Para que serve
PGP Pretty Good Privacy, tecnologia historicamente associada a criptografia e assinaturas digitais Proteger e autenticar informações
OpenPGP Padrão aberto para mensagens, chaves e assinaturas criptográficas Permitir interoperabilidade entre ferramentas
GPG / GnuPG Software livre que implementa OpenPGP Gerenciar chaves, criptografar, descriptografar e assinar
SSH Secure Shell, protocolo de comunicação e autenticação seguras Acessar servidores e repositórios remotos
gpg-agent Programa que gerencia operações com chaves privadas do GnuPG Autorizar assinaturas e, quando habilitado, atender clientes SSH

Imagine a chave pública como um cadeado que você pode entregar a outras pessoas e a chave privada como o segredo necessário para operar sua identidade criptográfica. É apenas uma analogia: o funcionamento de assinaturas digitais e criptografia é diferente, mas a ideia central permanece — a chave privada não deve ser compartilhada.

Quando alguém criptografa uma mensagem para sua chave pública, somente quem tem acesso à chave privada correspondente consegue normalmente descriptografá-la. Quando você assina digitalmente um arquivo, terceiros podem verificar a assinatura usando sua chave pública.

E onde o SSH entra nessa história?

Normalmente, o SSH usa arquivos como ~/.ssh/id_ed25519 e ~/.ssh/id_ed25519.pub. Com GPG, podemos criar uma subchave de autenticação e fazer o gpg-agent agir como um agente SSH. Assim, o cliente ssh pede a autenticação ao agente, sem precisar de uma cópia separada da chave privada em ~/.ssh.

Importante: assinatura GPG de commits e autenticação SSH são tarefas distintas. Elas podem fazer parte da mesma identidade OpenPGP, mas normalmente usam subchaves diferentes.

2. Por que usar GPG no dia a dia?

O GPG é útil para:

  • Assinar commits e tags: comprovar criptograficamente a assinatura de alterações no código.
  • Criptografar arquivos: proteger documentos, backups e informações confidenciais.
  • Assinar arquivos distribuídos: permitir que outras pessoas verifiquem a integridade e a autoria associada à chave.
  • Trocar mensagens protegidas: criptografar conteúdo para destinatários que tenham chaves OpenPGP.
  • Autenticar via SSH: utilizar uma subchave de autenticação em servidores e serviços como GitHub.
  • Integrar tokens físicos: em configurações avançadas, armazenar subchaves em dispositivos compatíveis com OpenPGP, como alguns modelos de smartcard e YubiKey.

Ter uma identidade GPG não substitui uma política de acesso, o gerenciamento de permissões ou a autenticação multifator. Da mesma forma, uma assinatura válida prova que determinada chave assinou o conteúdo, não garante, sozinha, que o proprietário da chave é quem afirma ser. A verificação da identidade e a proteção da chave privada continuam sendo essenciais.

3. Entendendo chaves e subchaves

Uma identidade OpenPGP pode ter uma chave primária e várias subchaves, cada qual com uma função. No GPG, as capacidades são geralmente exibidas assim:

Símbolo Capacidade Exemplo
[C] Certify — certificar chaves e identidades Gerenciar a identidade OpenPGP
[S] Sign — assinar Assinar commits e documentos
[E] Encrypt — criptografar Receber arquivos criptografados
[A] Authenticate — autenticar Efetuar login via SSH

Uma organização possível é:

Minha identidade OpenPGP
│
├── Chave primária Ed25519 [C]     → certificação e gerenciamento
├── Subchave Ed25519 [S]          → assinatura de commits/arquivos
├── Subchave Curve25519 [E]       → criptografia
└── Subchave Ed25519 [A]          → autenticação SSH

Recomendação: usar subchaves separadas facilita substituir uma credencial comprometida sem recriar toda a identidade. Em ambientes de segurança mais elevada, é comum manter a chave primária fora da estação de trabalho cotidiana e usar somente as subchaves necessárias. Essa é uma etapa avançada, não exigida para acompanhar o guia.

4. Instalando as ferramentas

Você precisará de gpg, gpg-agent, gpg-connect-agent, gpgconf, ssh, ssh-add e git. Verifique as versões:

gpg --version
ssh -V
git --version

Ubuntu e Debian

sudo apt update
sudo apt install gnupg openssh-client git pinentry-curses

Em ambientes gráficos, você pode preferir um pinentry gráfico compatível com sua distribuição.

Arch Linux

sudo pacman -S gnupg openssh git pinentry

Fedora

sudo dnf install gnupg2 openssh-clients git pinentry

macOS

Com Homebrew:

brew install gnupg pinentry-mac git

Também é possível usar o GPG Suite. Se o pedido de senha não funcionar, será necessário configurar o caminho correto do pinentry-program em ~/.gnupg/gpg-agent.conf de acordo com a instalação. Não copie caminhos de outros sistemas sem verificá-los.

Windows

Instale o Gpg4win e o Git for Windows. O GnuPG também pode integrar-se ao OpenSSH do Windows, mas o encaminhamento entre o agente e o OpenSSH varia conforme a versão e o terminal (PowerShell, Git Bash ou WSL). Os comandos de socket Unix apresentados nas próximas seções são voltados principalmente a Linux/macOS. No WSL, siga o procedimento Linux dentro do WSL, lembrando que o chaveiro do WSL e o do Windows não são necessariamente o mesmo.

5. Criando uma identidade GPG

Se já possui uma chave GPG, não precisa criar outra. Primeiro, inspecione as existentes:

gpg --list-secret-keys --keyid-format LONG
gpg --list-secret-keys --with-subkey-fingerprint --with-keygrip

Se uma subchave [A] já existir e tiver material privado acessível, prossiga para a configuração do agente.

5.1 Gere a chave primária

Neste exemplo, vamos criar uma chave primária Ed25519 dedicada à certificação. Substitua nome e email pelos seus dados:

gpg --quick-generate-key "Seu Nome <voce@example.com>" ed25519 cert 2y

O GPG solicitará a confirmação e a criação de uma senha forte (passphrase). Não a reutilize em outros serviços.

Por que cert? Porque vamos reservar a chave primária para gerenciar a identidade, enquanto subchaves separadas farão assinaturas, criptografia e autenticação. Esse formato exige versões do GnuPG que aceitem os comandos --quick-* e os algoritmos indicados.

5.2 Identifique o fingerprint

gpg --list-secret-keys --with-subkey-fingerprint

Exemplo ilustrativo (os valores reais serão diferentes):

sec   ed25519 2026-10-21 [C] [expires: 2028-10-20]
      0123456789ABCDEF0123456789ABCDEF01234567
uid           Seu Nome <voce@example.com>

A sequência longa de caracteres hexadecimais é o fingerprint, uma identificação mais precisa que o identificador abreviado da chave. Copie o fingerprint da chave primária e utilize-o nos próximos comandos.

Para simplificar os exemplos, definiremos uma variável temporária no terminal:

# Substitua pelo fingerprint real da SUA chave primária.
FPR="0123456789ABCDEF0123456789ABCDEF01234567"

5.3 Adicione subchaves de assinatura, autenticação e criptografia

# Assinar commits, tags e arquivos.
gpg --quick-add-key "$FPR" ed25519 sign 1y

# Autenticar-se em serviços e servidores via SSH.
gpg --quick-add-key "$FPR" ed25519 auth 1y

# Receber conteúdo criptografado (opcional, mas útil).
gpg --quick-add-key "$FPR" cv25519 encr 1y

Confira o resultado:

gpg --list-secret-keys --with-subkey-fingerprint --with-keygrip "$FPR"

Você deverá encontrar entradas com [C], [S], [A] e [E]. Uma instalação mais antiga pode apresentar detalhes de formato diferentes.

Observação: Ed25519 é usado para assinatura/autenticação; Curve25519 (cv25519, no contexto GnuPG) é apropriado à subchave de criptografia. Não use a subchave [E] como identidade SSH.

6. Configurando o GPG como agente SSH

Agora vamos fazer o OpenSSH conversar com o gpg-agent.

6.1 Habilite o suporte SSH

Crie o diretório de configuração, caso ele não exista, e proteja suas permissões:

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg

Abra o arquivo ~/.gnupg/gpg-agent.conf em seu editor e adicione a linha abaixo uma única vez:

enable-ssh-support

Reinicie o agente para aplicar essa opção:

gpgconf --kill gpg-agent
gpg-connect-agent /bye

6.2 Aponte o SSH para o socket correto

Em Linux/macOS, descubra o socket SSH exposto pelo GPG:

gpgconf --list-dirs agent-ssh-socket

Para testar na sessão atual:

export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
unset SSH_AGENT_PID

# Se estiver em um terminal interativo:
export GPG_TTY="$(tty)"
gpg-connect-agent updatestartuptty /bye

Se funcionar, coloque estas instruções no arquivo de inicialização do shell em que você trabalha (por exemplo, ~/.bashrc ou ~/.zshrc):

# Permite que SSH use o gpg-agent em vez de outro ssh-agent.
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
unset SSH_AGENT_PID

# Evita invocar 'tty' quando não há terminal interativo.
if [ -t 0 ]; then
    export GPG_TTY="$(tty)"
    gpg-connect-agent updatestartuptty /bye >/dev/null
fi

Depois, abra um novo terminal e confirme:

printf 'SSH_AUTH_SOCK=%s\n' "$SSH_AUTH_SOCK"

Atenção em ambientes gráficos: gerenciadores de sessão, systemd, launchd e agentes SSH já existentes podem sobrescrever SSH_AUTH_SOCK. Em alguns desktops, é mais adequado configurar a variável na inicialização da sessão gráfica do que apenas no ~/.bashrc.

6.3 Autorize a subchave de autenticação no GPG Agent

Primeiro, identifique o keygrip da subchave marcada com [A]:

gpg --list-secret-keys --with-keygrip --with-subkey-fingerprint "$FPR"

Saída de exemplo (resumida):

ssb   ed25519 2026-10-21 [A] [expires: 2027-10-21]
      89ABCDEF0123456789ABCDEF0123456789ABCDEF
      Keygrip = FEDCBA9876543210FEDCBA9876543210FEDCBA98

Copie o Keygrip da subchave [A], não o fingerprint da chave primária.

Em versões recentes do GnuPG que suportam o atributo Use-for-ssh, faça:

# Substitua pelo keygrip real da subchave [A].
AUTH_KEYGRIP="FEDCBA9876543210FEDCBA9876543210FEDCBA98"

gpg-connect-agent "KEYATTR ${AUTH_KEYGRIP} Use-for-ssh: true" /bye

O atributo é persistente e indica que a subchave pode ser apresentada pelo agente ao SSH.

Compatibilidade com versões antigas: alguns ambientes usam o arquivo ~/.gnupg/sshcontrol, abordagem hoje considerada legada. Se sua versão não aceitar KEYATTR ... Use-for-ssh:, você pode registrar o keygrip da subchave [A] nesse arquivo:

# Alternativa legada: execute SOMENTE se sua versão exigir sshcontrol.
printf '%s\n' "$AUTH_KEYGRIP" >> ~/.gnupg/sshcontrol
chmod 600 ~/.gnupg/sshcontrol

Evite registrar o mesmo keygrip repetidamente. Prefira Use-for-ssh onde estiver disponível.

6.4 Verifique se o SSH enxerga a chave

gpg-connect-agent /bye
ssh-add -L

Você deve ver uma chave pública SSH (geralmente começando com ssh-ed25519). Para conferir as impressões digitais:

ssh-add -l

Não use ssh-add ~/.gnupg/... para tentar carregar uma subchave OpenPGP. Diferentemente dos arquivos privados tradicionais do OpenSSH, essa subchave é gerenciada pelo GPG e exposta pelo agente.

6.5 Exporte apenas a chave pública em formato SSH

mkdir -p ~/.ssh
chmod 700 ~/.ssh

gpg --export-ssh-key "$FPR" > ~/.ssh/gpg_auth.pub
chmod 644 ~/.ssh/gpg_auth.pub
cat ~/.ssh/gpg_auth.pub

O conteúdo deverá se parecer com:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... openpgp:0x...

Esse arquivo .pub pode ser distribuído para permitir autenticação; ele não contém a chave privada. O arquivo é diferente da exportação OpenPGP (gpg --armor --export), usada para criptografia e verificação de assinaturas GPG.

Caso existam várias subchaves de autenticação, confirme qual está sendo exportada. O GPG permite selecionar uma subchave específica com seu fingerprint seguido de !; isso só é necessário em configurações mais avançadas.

7. Usando a chave no GitHub e em servidores

7.1 Cadastre a chave no GitHub para autenticação SSH

  1. Abra GitHub → Settings → SSH and GPG keys.
  2. Clique em New SSH key.
  3. Informe um título como Notebook pessoal — GPG.
  4. Selecione o tipo Authentication Key.
  5. Cole o conteúdo de ~/.ssh/gpg_auth.pub e salve.

Página de configurações: https://github.com/settings/keys

Não envie seu arquivo de chave privada e não cole o bloco OpenPGP no campo de chave SSH.

7.2 Teste a autenticação

ssh -T git@github.com

Uma resposta de sucesso normalmente informa que você se autenticou, mas o GitHub não oferece acesso a um shell. O comando pode terminar com código de saída 1 mesmo quando a autenticação foi bem-sucedida.

Na primeira conexão, confira o fingerprint da chave do servidor GitHub com a documentação oficial de fingerprints SSH antes de aceitar a identidade do host.

Se for necessário investigar:

ssh -vT git@github.com

7.3 Configure seu repositório para usar SSH

Dentro do diretório de um projeto Git:

# Troque USUARIO e REPOSITORIO pelos valores corretos.
git remote set-url origin git@github.com:USUARIO/REPOSITORIO.git

git remote -v

Agora git fetch, git pull e git push poderão usar a autenticação oferecida pelo gpg-agent, desde que sua conta tenha permissão sobre o repositório.

7.4 Use em um servidor Linux

Adicione a chave pública SSH exportada ao arquivo ~/.ssh/authorized_keys do usuário remoto, preservando as permissões corretas do diretório .ssh e desse arquivo. Depois, conecte:

ssh usuario@servidor.exemplo.com

Se você administra o servidor, valide as configurações de autenticação SSH antes de alterar políticas de login; mantenha um método de recuperação para não se bloquear acidentalmente.

7.5 Opcional: selecione a identidade em ~/.ssh/config

Se você possui várias chaves e o SSH escolhe a errada, pode indicar a chave pública correspondente ao agente GPG:

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

Esse ajuste é opcional, e pressupõe que o cliente OpenSSH consiga encontrar a chave privada correspondente por meio do gpg-agent. Não há necessidade de inventar um arquivo privado ~/.ssh/gpg_auth.

8. Assinando commits e tags do Git

Até aqui usamos a subchave [A] para autenticação SSH. Agora usaremos a subchave [S] para assinaturas digitais OpenPGP, uma função independente.

8.1 Configure nome e email

git config --global user.name "Seu Nome"
git config --global user.email "voce@example.com"

Para que o GitHub associe suas assinaturas à conta e exiba corretamente o estado de verificação, observe os requisitos de identidade, endereço de email verificado e chave pública cadastrada no serviço.

8.2 Configure o Git para assinar com GPG

# Define explicitamente que queremos assinatura OpenPGP, e não assinatura SSH.
git config --global gpg.format openpgp

# Ajuste o executável caso seu sistema use outro caminho, como gpg2.
git config --global gpg.program gpg

# Utilize o fingerprint da chave primária associada à subchave [S].
git config --global user.signingkey "$FPR"

# Assine commits automaticamente.
git config --global commit.gpgsign true

O GPG normalmente escolhe uma subchave de assinatura válida vinculada à identidade selecionada. Se houver várias subchaves [S], uma configuração avançada pode selecionar uma subchave específica.

8.3 Publique sua chave pública OpenPGP no GitHub

gpg --armor --export "$FPR"

Copie o bloco completo:

-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----

No GitHub, acesse Settings → SSH and GPG keys → New GPG key e cole o conteúdo.

Duas ações diferentes no GitHub:

Objetivo Chave cadastrada Local
Clonar/enviar código por SSH Chave pública exportada por gpg --export-ssh-key SSH keys → Authentication Key
Verificar assinatura OpenPGP de commits Chave pública exportada por gpg --armor --export GPG keys

O GitHub também oferece assinatura de commits com SSH. É outra modalidade: exigiria gpg.format ssh e a chave SSH cadastrada como Signing Key. Neste artigo, adotamos SSH para autenticação e OpenPGP/GPG para assinatura de commits, para manter as responsabilidades separadas.

8.4 Faça seu primeiro commit assinado

Num repositório com alterações prontas para commit:

git add .
git commit -S -m "docs: adiciona documentação inicial"

O parâmetro -S solicita assinatura explicitamente; com commit.gpgsign=true, commits normais também serão assinados.

Para ver a assinatura no histórico:

git log --show-signature -1
git verify-commit HEAD

O que significa Good signature? Significa que a assinatura corresponde ao conteúdo e à chave pública verificada pelo GPG. Isso não é sinônimo de que a identidade humana já foi validada em uma cadeia de confiança; avisos sobre confiança local podem aparecer mesmo com uma assinatura criptograficamente correta.

8.5 Assine versões do projeto com tags

git tag -s v1.0.0 -m "Lançamento da versão 1.0.0"
git tag -v v1.0.0

git push origin main
git push origin v1.0.0

Ajuste main para a branch correta. A verificação de commits/tags por terceiros exige acesso à sua chave pública GPG.

9. Criptografando e assinando arquivos

O GPG não serve apenas para Git e SSH. Veja usos cotidianos.

9.1 Criptografar um arquivo para si mesmo

Crie um arquivo de exemplo e criptografe-o com a subchave [E]:

printf 'Este conteúdo é privado.\n' > mensagem.txt

gpg --output mensagem.txt.gpg \
    --encrypt --recipient "$FPR" mensagem.txt

Para recuperar o conteúdo:

gpg --output mensagem-recuperada.txt \
    --decrypt mensagem.txt.gpg

Cuidado: mensagem.txt continua em texto puro! A criptografia cria um novo arquivo; ela não elimina cópias originais, backups nem históricos de edição. Não coloque arquivos sensíveis ou descriptografados em repositórios Git.

9.2 Criptografar para outra pessoa

Primeiro, receba a chave pública OpenPGP da pessoa, confira seu fingerprint por um canal confiável e importe-a:

gpg --import chave-publica-do-destinatario.asc

Depois, use o fingerprint verificado do destinatário:

gpg --encrypt --recipient FINGERPRINT_DO_DESTINATARIO \
    --output arquivo.gpg arquivo.txt

9.3 Assinar um arquivo separadamente

gpg --armor --detach-sign --output arquivo.txt.asc.sig arquivo.txt

Para verificar:

gpg --verify arquivo.txt.asc.sig arquivo.txt

Esse método permite enviar o arquivo original e a assinatura lado a lado. Quem verifica precisa obter uma cópia confiável da chave pública correspondente.

10. Backup, revogação e segurança

Sua chave privada é um ativo de segurança. Perder seu acesso pode impedir a descriptografia de arquivos antigos e a utilização de credenciais relacionadas.

Faça backup com cuidado

O comando abaixo exporta material privado. Execute-o somente quando souber onde o arquivo será salvo e puder protegê-lo imediatamente:

umask 077

gpg --armor --export-secret-keys "$FPR" > minha-chave-privada-backup.asc

gpg --armor --export "$FPR" > minha-chave-publica.asc

gpg --export-ownertrust > confianca-gpg-backup.txt

Atenção: o arquivo minha-chave-privada-backup.asc é extremamente sensível. Mesmo que as chaves estejam protegidas por passphrase, uma exportação da chave privada não deve ser enviada por email, publicada no Git, guardada em serviços sem proteção adequada ou deixada em diretórios compartilhados. Armazene-o em mídia offline protegida, preferencialmente também criptografada, e exclua com segurança as cópias temporárias conforme os recursos do sistema.

Prepare um plano de revogação

O GPG costuma criar um certificado de revogação na geração da chave, dentro de ~/.gnupg/openpgp-revocs.d/. Confira se ele existe e guarde uma cópia protegida e separada. Também é possível gerar um certificado de revogação com:

gpg --output revogacao.asc --gen-revoke "$FPR"

Não importe ou publique o certificado de revogação como teste: ele serve para declarar que a chave foi revogada. Sua publicação deve ser uma decisão consciente e normalmente não reversível no ecossistema de distribuição de chaves.

Recomendações práticas

  • Proteja a chave com uma passphrase exclusiva e forte.
  • Prefira subchaves separadas para [S], [A] e [E].
  • Defina prazos de expiração e mantenha um procedimento para renová-los.
  • Proteja ~/.gnupg e evite copiar diretórios privados sem necessidade.
  • Use autenticação multifator na conta GitHub, mesmo autenticando via SSH.
  • Remova chaves SSH antigas das contas e dos servidores quando forem substituídas.
  • Avalie smartcards/tokens físicos quando seu modelo de ameaça justificar.
  • Não exponha o socket do agente (SSH_AUTH_SOCK) a processos ou usuários não confiáveis.
  • Tenha cópia de recuperação e teste se ela pode ser restaurada em um ambiente seguro.

11. Solução de problemas

ssh-add -L diz que não há identidades

Verifique, nesta ordem:

# 1. Suporte SSH habilitado em ~/.gnupg/gpg-agent.conf?
# 2. O agente está em execução?
gpg-connect-agent /bye

# 3. SSH aponta para o agente correto?
printf '%s\n' "$SSH_AUTH_SOCK"
gpgconf --list-dirs agent-ssh-socket

# 4. Existe subchave de autenticação com keygrip correto?
gpg --list-secret-keys --with-keygrip "$FPR"

# 5. O agente tem chaves habilitadas para SSH?
ssh-add -L

Se necessário, confira o registro Use-for-ssh da subchave [A] ou o sshcontrol legado; reinicie o agente e abra outro terminal.

Permission denied (publickey) no GitHub

Possíveis causas: a chave pública não está cadastrada como Authentication Key, o SSH_AUTH_SOCK aponta para outro agente, a subchave expirou, a conta não tem acesso ao repositório ou o SSH está tentando uma identidade diferente.

ssh -vT git@github.com

Analise as identidades oferecidas e compare com ssh-add -L.

gpg: signing failed: Inappropriate ioctl for device

Em Linux/macOS, atualize o terminal e o agente:

export GPG_TTY="$(tty)"
gpg-connect-agent updatestartuptty /bye

Confira também o pinentry instalado, o terminal interativo e qualquer integração com IDE.

O Git não mostra o selo Verified

Verifique se a chave OpenPGP pública foi cadastrada em GPG keys, se a assinatura é válida e se a identidade/email atendem aos requisitos da plataforma. Autenticar-se via SSH não assina os commits automaticamente.

git config --show-origin --get gpg.format
git config --show-origin --get user.signingkey
git config --show-origin --get commit.gpgsign
git log --show-signature -1

GPG funciona no terminal, mas não na IDE

Algumas IDEs são abertas a partir de uma sessão gráfica que não herdou GPG_TTY ou SSH_AUTH_SOCK. Compare as variáveis de ambiente da IDE com as do terminal; configure-as na sessão apropriada e verifique o diálogo de pinentry.

Existem dois agentes SSH competindo

Se ssh-agent e gpg-agent estiverem ativos ao mesmo tempo, não há necessariamente um problema. A questão é qual socket o processo ssh está usando. Veja:

printf '%s\n' "$SSH_AUTH_SOCK"
ssh-add -L

Se precisar de seleção por host, use ~/.ssh/config. Não remova serviços do sistema sem entender a integração com sua sessão gráfica.

A chave ou subchave expirou

Inspecione datas e fingerprints:

gpg --list-secret-keys --with-subkey-fingerprint "$FPR"

Planeje renovar a validade com os comandos de gerenciamento do GPG ou criar e distribuir uma subchave substituta. Quando trocar a subchave [A], atualize as chaves SSH cadastradas nos serviços e servidores. A atualização da validade de uma chave OpenPGP pode exigir republicar a chave pública atualizada para que verificadores conheçam seus novos metadados.

12. Perguntas frequentes

Preciso abandonar minhas chaves SSH tradicionais?

Não. Você pode manter chaves tradicionais e usar uma subchave GPG apenas onde fizer sentido. A vantagem da integração é centralizar determinadas operações no gpg-agent.

A chave que assina commits é a mesma que abre uma sessão SSH?

Neste guia, não. A identidade OpenPGP é a mesma, mas são utilizadas as subchaves [S] (assinatura) e [A] (autenticação), respectivamente.

Posso usar GPG no GitHub e GitLab?

Sim. Ambos aceitam autenticação Git por SSH e oferecem mecanismos de verificação de assinaturas. As telas, os requisitos de email e as políticas de assinatura podem variar; consulte a documentação do serviço usado.

GPG substitui o HTTPS do Git?

Não. HTTPS e SSH são alternativas para acessar repositórios remotos. O GPG, neste cenário, fornece a subchave de autenticação que pode operar por SSH e a subchave que assina commits. O transporte continua sendo SSH quando a URL remota é git@....

Posso usar uma YubiKey?

Em muitos cenários, sim, com um dispositivo compatível com a aplicação OpenPGP. O processo envolve geração/importação de subchaves, configuração do cartão e planejamento de recuperação. Não mova sua única cópia de uma subchave para o dispositivo sem um backup adequado.

Qual comando devo lembrar?

# Ver suas chaves e capacidades
gpg --list-secret-keys --with-subkey-fingerprint --with-keygrip

# Ver identidades SSH oferecidas pelo agente
ssh-add -L

# Exportar uma chave pública para cadastro no SSH
gpg --export-ssh-key SEU_FINGERPRINT

# Exportar sua chave pública OpenPGP
gpg --armor --export SEU_FINGERPRINT

# Verificar autenticação no GitHub
ssh -T git@github.com

# Verificar a assinatura do último commit
git log --show-signature -1

13. Referências e documentação oficial

As recomendações foram estruturadas com base principalmente na documentação oficial das ferramentas:

Conclusão

O GPG é mais do que uma ferramenta de criptografar arquivos: ele pode funcionar como o centro de uma identidade criptográfica, com subchaves destinadas a tarefas diferentes. Ao integrá-lo ao OpenSSH por meio do gpg-agent, você autentica conexões e operações Git sem duplicar a chave privada em arquivos SSH tradicionais. Com outra subchave, assina commits e tags; com uma terceira, recebe arquivos criptografados.

O segredo para fazer isso com tranquilidade é separar as responsabilidades, conferir os fingerprints, proteger as chaves privadas e planejar a recuperação antes de precisar dela.

#gpg #git #github #gitlab #ssh
Write a comment