Assinar Commits Git com GPG e SSH

Assinar um commit anexa uma assinatura criptográfica que prova quem o criou e que seu conteúdo não foi alterado. Este capítulo explica por que as assinaturas importam, como gerar uma chave, como assinar commits e tags com GPG ou SSH, como verificar assinaturas e como corrigir os erros que você provavelmente encontrará na primeira vez.

O que a assinatura realmente prova

Por padrão, o nome do autor e o e-mail em um commit são apenas texto. O Git nunca os verifica — qualquer pessoa pode definir user.name e user.email com qualquer valor (veja git config) e produzir um commit que afirma ser de outra pessoa. Uma assinatura muda isso: ela é feita com uma chave privada que só você possui, e qualquer pessoa com sua chave pública correspondente pode confirmar duas coisas:

Autoria — o commit realmente veio do detentor dessa chave privada.
Integridade — se um único byte do commit (mensagem, árvore, pai, autor) mudar, a verificação falha.

Para projetos onde a procedência importa — código sensível à segurança, lançamentos de código aberto, ambientes regulamentados — o histórico assinado permite que os revisores confiem em quem escreveu o quê. No GitHub e no GitLab, uma assinatura verificada ganha um selo verde Verificado ao lado do commit.

Nota

Uma assinatura não criptografa nada. O commit e seu conteúdo permanecem totalmente legíveis; a assinatura apenas atesta a origem e a integridade.

Escolhendo GPG ou SSH

O Git suporta dois formatos de assinatura. Escolha um:

GPG (OpenPGP) — a escolha tradicional. Maduro, amplamente suportado, mas o gerenciamento de chaves (keyrings, expiração, o agente gpg) tem uma curva de aprendizado.
SSH — disponível desde o Git 2.34. Se você já usa uma chave SSH para enviar, pode reutilizá-la para assinar com quase nenhuma configuração extra. Mais simples de gerenciar, agora é o ponto de partida recomendado para a maioria das pessoas.

Verifique sua versão primeiro:

git --version

Assinando com GPG

Gerar ou encontrar uma chave

Se você ainda não tem uma chave GPG, crie uma (aceite os padrões, escolhendo uma RSA de 4096 bits ou uma chave ECC):

gpg --full-generate-key

Liste suas chaves e copie o ID longo da chave — o valor após o algoritmo na linha sec:

gpg --list-secret-keys --keyid-format=long

sec   ed25519/3AA5C34371567BD2 2024-01-08 [SC]
      AB1C2D3E...
uid   Jane Dev <[email protected]>

Aqui o ID da chave é 3AA5C34371567BD2.

Configurar o Git

git config --global user.signingkey 3AA5C34371567BD2
git config --global commit.gpgsign true

Assinar um commit ou tag

Com commit.gpgsign ativado, cada commit é assinado automaticamente. Para assinar um único commit explicitamente, use o sinalizador -S maiúsculo:

git commit -S -m "Add audited payment handler"

Para assinar uma tag anotada, use o -s minúsculo:

git tag -s v2.0.0 -m "Signed release 2.0.0"

Aviso

O caso importa: -S (maiúsculo) assina um commit, enquanto -s (minúsculo) assina uma tag. No git commit, o -s minúsculo adiciona uma linha Signed-off-by — um Certificado de Origem do Desenvolvedor em texto simples, não uma assinatura criptográfica.

Assinando com SSH

Se você tem uma chave id_ed25519 (ou qualquer chave SSH), aponte o Git para a chave pública e mude o formato de assinatura:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Commits e tags agora assinam com os mesmos sinalizadores -S / -s de antes — nenhuma outra alteração é necessária.

Habilitar verificação local para SSH

Ao contrário do GPG, o Git não tem um repositório de confiança integrado para chaves SSH, então git log --show-signature relata No principal matched até você criar um arquivo de signatários permitidos. Mapeie cada e-mail para sua chave pública:

mkdir -p ~/.config/git
echo "[email protected] $(cat ~/.ssh/id_ed25519.pub)" >> ~/.config/git/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers

Enviando sua chave pública ao host

O selo Verificado só aparece depois que o host tiver sua chave pública registrada.

GPG: copie a chave pública blindada de gpg --armor --export <key-id> e cole-a em Configurações → Chaves SSH e GPG → Nova chave GPG.
SSH: adicione o conteúdo de ~/.ssh/id_ed25519.pub como uma chave do tipo Chave de assinatura (separada de uma chave de autenticação) na mesma área de configurações.

O e-mail na sua chave deve corresponder ao e-mail do autor do commit, ou o host mostrará Não verificado.

Verificando assinaturas

Verifique assinaturas localmente com qualquer um destes:

git log --show-signature          # show signature status in the log
git verify-commit HEAD            # verify one commit
git verify-tag v2.0.0             # verify a tag

Para uma visualização compacta, o marcador %G? no git log imprime um código de status por commit:

git log --pretty="%h %G? %s"

a1b2c3d G  Add audited payment handler
d4e5f6g N  Quick typo fix

G significa uma assinatura boa (válida), B ruim, U boa com validade desconhecida e N sem assinatura.

Erros comuns e correções

error: gpg failed to sign the data — geralmente o agente GPG não consegue solicitar sua senha. Exporte o terminal que ele deve usar: export GPG_TTY=$(tty) (adicione ao ~/.bashrc ou ~/.zshrc). No macOS, instale pinentry-mac para que o agente possa exibir um diálogo de senha.
gpg: signing failed: No secret key — user.signingkey aponta para o ID errado. Verifique novamente com gpg --list-secret-keys --keyid-format=long.
GitHub mostra Não verificado — o e-mail do autor do commit não corresponde a um e-mail vinculado à sua chave enviada, ou a chave não foi adicionada ao host.
No principal matched (SSH) — você não configurou gpg.ssh.allowedSignersFile (veja acima).

Opções comuns

Comando	Descrição
`git commit -S`	Assina um único commit.
`git tag -s <name>`	Cria uma tag anotada assinada.
`git config commit.gpgsign true`	Assina todos os commits automaticamente.
`git config gpg.format ssh`	Assinar com uma chave SSH em vez de GPG.
`git log --show-signature`	Exibe o status da assinatura no log.
`git log --pretty="%G?"`	Imprime um código de status de assinatura por commit.
`git verify-commit <commit>`	Verifica a assinatura de um commit.
`git verify-tag <tag>`	Verifica a assinatura de uma tag.

Prática

Quais afirmações sobre a assinatura de commits estão corretas?

Uma assinatura prova a autoria e garante que o conteúdo do commit não foi alterado.Sem assinatura, o nome do autor e o e-mail em um commit podem ser definidos com qualquer valor.O Git pode assinar commits com uma chave GPG ou, em versões modernas, uma chave SSH.'commit.gpgsign true' assina todos os commits automaticamente.Uma assinatura é impossível de verificar localmente e só funciona em plataformas de hospedagem.