Como usar o git crypt

, ,

Quando você precisa armazenar informações sigilosas dentro do seu repositorio git uma boa opção é usar o git-crypt.
Segue um passo a passo.

1. Pré-requisitos

Instala em sua máquina:

1
2
3
4
5
# Debian/Ubuntu
sudo apt install git-crypt gnupg

# Fedora
sudo dnf install git-crypt gnupg

Confere se está ok:

1
2
git-crypt --version
gpg --version

2. Criar (ou usar) uma chave GPG moderna (EdDSA + ECDH – Curve25519)

Recomendo utilizar uma chave EdDSA em vez de usar RSA.

Se você já possui uma chave GPG e ela é compatível com criptografia (não apenas assinatura), pode pular para o passo 3.
Caso deseje criar uma chave moderna usando curvas elípticas, siga este processo:

2.1. Criar chave ECC (EdDSA + ECDH) com GPG

Execute o modo avançado para acessar as curvas modernas:

1
gpg --expert --full-generate-key

Agora escolha:

  1. Tipo de chave
    Selecione:

    1
    (9) ECC and ECC

  2. Função da chave
    Geralmente o GPG perguntará qual tipo de curva deve ser usada.
    Escolha:

    1
    (1) Curve 25519

    Isso cria:

    • Ed25519 para assinatura (EdDSA)
    • Curve25519 (cv25519) para criptografia (ECDH)

  3. Informações pessoais

    • Nome
    • Email (use o mesmo do seu Git)
    • Comentário (opcional)

  4. Expiração
    Pode usar:

    • sem expiração, ou
    • 2 anos, renovando quando quiser.

  5. Senha da chave
    Uma senha forte é recomendada.

  6. Pontos de atenção (compatibilidade)

GPG antigo (principalmente em Windows/ambiente legado) pode ter suporte ruim ou limitado para algumas curvas ECC mais novas.

Se você usa CI/CD, garanta que o ambiente de build também:

tenha gpg com suporte a ECC

tenha a chave privada importada (ou use git-crypt export-key e git-crypt unlock no CI).

2.2. Confirmar a criação e obter o ID da chave

Liste suas chaves privadas:

1
gpg --list-secret-keys --keyid-format LONG

Você verá algo como:

1
2
3
4
sec   ed25519/ABCDEF1234567890 2025-11-29 [SC]
      F1A2B3C4D5E6F7890ABCDEF1234567890ABCDEF12
uid           [ultimate] Seu Nome <voce@exemplo.com>
ssb   cv25519/0123456789ABCDEF 2025-11-29 [E]

Observe que:

  • ed25519 = assinatura (EdDSA)
  • cv25519 = criptografia (ECDH)

O identificador da chave que você usará no git-crypt é o que aparece após ed25519/, por exemplo:

1
ABCDEF1234567890

2.3. Pronto!

Agora você tem uma chave moderna ECC, com:

  • EdDSA (Ed25519) para assinatura
  • ECDH (Curve25519) para criptografia

E ela funciona perfeitamente com o git-crypt através do comando:

1
git-crypt add-gpg-user ABCDEF1234567890

3. Iniciar o git-crypt no repositório

Entre no diretório do seu repo:

1
cd /caminho/do/seu/repo

Inicie o git-crypt:

1
git-crypt init

Isso cria a estrutura interna .git-crypt/ no repositório (vai ser commitado depois).

4. Configurar o .gitattributes

No raiz do repositório, crie (ou edite) o arquivo .gitattributes:

1
vim .gitattributes

Adicione as regras dos arquivos que você quer criptografar. Exemplos:

1
2
3
4
5
6
7
8
9
# Arquivos de secrets
secrets/*.json     filter=git-crypt diff=git-crypt

# Configs sensíveis de produção
config/prod/*.yml  filter=git-crypt diff=git-crypt

# Chaves privadas
*.key              filter=git-crypt diff=git-crypt
*.pem              filter=git-crypt diff=git-crypt

Salve e faça commit disso:

1
2
git add .gitattributes
git commit -m "Configura git-crypt com .gitattributes"

Tudo que bater nesses padrões será armazenado criptografado no Git/remote, mas aparecerá descriptografado no seu working directory quando o repo estiver “desbloqueado”.

5. Adicionar seu usuário GPG ao git-crypt

Agora diga ao git-crypt que este repositório pode ser desbloqueado pela sua chave GPG:

1
git-crypt add-gpg-user ABCDEF1234567890

Ou, se preferir, usando o email da chave:

1
git-crypt add-gpg-user voce@exemplo.com

Isso vai:

  • Criar os metadados de acesso dentro de .git-crypt/
  • Usar sua chave pública GPG para poder descriptografar a chave simétrica do repo

Depois:

1
2
git add .git-crypt
git commit -m "Habilita acesso via GPG para git-crypt"

6. Adicionar arquivos sensíveis e verificar criptografia

Agora coloque algum arquivo sensível num caminho coberto pelo .gitattributes, por exemplo:

1
2
3
4
5
mkdir -p secrets
echo '{ "apiKey": "123456" }' > secrets/config.json

git add secrets/config.json
git commit -m "Adiciona config sensível criptografada"

Como testar se está realmente criptografado no Git?

  1. No disco, o arquivo é legível normalmente.
  2. No repositório (objeto Git), ele deve estar em binário “lixo”.

Uma forma de checar:

1
git show HEAD:secrets/config.json | head

Você deve ver conteúdo ilegível (binário), não o JSON de verdade.

7. Clonar o repo e desbloquear com git-crypt + GPG

Para outro clone (ou outra máquina/usuário que tenha a chave privada GPG correspondente):

  1. Clona o repo normalmente:

    1
    2
    git clone git@github.com:seuuser/seurepo.git
    cd seurepo

  2. Garante que a chave GPG (com a private key) está importada:

    1
    2
    gpg --import sua-chave-privada.asc   # se for o caso
    gpg --list-secret-keys

  3. Desbloqueia o repositório:

    1
    git-crypt unlock

Se tudo estiver certo, os arquivos marcados em .gitattributes aparecem legíveis.

8. Ver alguns comandos úteis do git-crypt

  • Ver status:

    1
    git-crypt status

  • Bloquear novamente (por exemplo em CI, se quiser garantir nada descriptografado):

    1
    git-crypt lock

  • Exportar uma chave simétrica (para uso em ambiente sem GPG, como CI/CD):

    1
    git-crypt export-key ./git-crypt-key

    E no ambiente (CI, por ex.):

    1
    git-crypt unlock ./git-crypt-key

9. Fluxo típico resumido

  1. Criar/usar chave GPG (gpg --full-generate-key).
  2. git-crypt init no repo.
  3. Configurar .gitattributes com os paths sensíveis.
  4. git-crypt add-gpg-user <ID ou email> e commitar .git-crypt/.
  5. Adicionar/commitar arquivos sensíveis normalmente (eles serão criptografados no Git).
  6. Em qualquer clone com a private key GPG: git-crypt unlock.