Git-Crypt Guide: Secure File Management in Git

Table of Contents

Core Concepts of Git-Crypt

Git-crypt is a powerful tool that enables transparent encryption of sensitive files in Git repositories. It ensures that these files are encrypted when committed to the repository while remaining decrypted and usable in your working directory.

Key Features

1. Transparent Encryption

   • Files are automatically encrypted during commits
   • Automatically decrypted when checking out
   • Works seamlessly with normal Git workflows

2. Selective Encryption

   • Encrypt only specific files
   • Other files remain unencrypted
   • Configurable through .gitattributes

3. GPG Integration

   • Uses GPG for key management
   • Supports multiple users through GPG
   • Secure key sharing mechanism

Installation and Setup

Prerequisites

1. Git installed and configured
2. GPG installed and configured
3. Administrative privileges for installation

Installation Steps

Windows

1. Manual Installation (Recommended):

   # 1. Download the git-crypt.exe from the official repository
   # https://github.com/AGWA/git-crypt/releases
   
   # 2. Rename it to 'git-crypt.exe'
   
   # 3. Move it to Git Bash's bin directory
   # Path: C:/Users/[YourUsername]/AppData/Local/Programs/Git/mingw64/bin/
   

2. Using Scoop:

   scoop install git-crypt
   

3. Using Chocolatey:

   choco install git-crypt
   

macOS

Using Homebrew:

brew install git-crypt

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install git-crypt

Basic Usage

Initializing Git-Crypt in a Repository

1. Initialize git-crypt:

   git-crypt init
   

2. Create .gitattributes:

   secretfile.txt filter=git-crypt diff=git-crypt
   *.key filter=git-crypt diff=git-crypt
   secret/* filter=git-crypt diff=git-crypt
   

3. Add and commit files:

   git add .
   git commit -m "Add encryption"
   

Adding Users

1. Export the key:

   git-crypt export-key /path/to/key
   

2. Share the key securely with team members

3. Team members unlock the repository:

   git-crypt unlock /path/to/key
   

Using GPG

1. Add users using GPG:

   git-crypt add-gpg-user USER_ID
   

2. Clone and unlock:

   git clone /path/to/repo
   git-crypt unlock
   

Best Practices

File Selection

1. What to Encrypt

   • API keys and secrets
   • Configuration files with sensitive data
   • Private certificates and keys
   • Environment files (.env)

2. What Not to Encrypt

   • Public documentation
   • Source code
   • Test files
   • Public configurations

Security Considerations

1. Key Management

   • Store keys securely
   • Use GPG when possible
   • Regular key rotation
   • Maintain key backup

2. Access Control

   • Limit number of users with access
   • Regular access review
   • Document key holders
   • Plan for user offboarding

Workflow Integration

1. CI/CD Considerations

   • Automated unlocking in pipelines
   • Secure key storage in CI systems
   • Testing encrypted files

2. Team Workflow

   • Document encryption procedures
   • Clear onboarding process
   • Regular encryption audits

Encrypting Existing Repositories

For existing repositories, follow the same steps as new ones. Note: Files in commit history remain visible; only new commits will be encrypted.

Key Management

Key Backup

1. Export the symmetric key:

   git-crypt export-key ~/git-crypt-key
   

2. Store the key securely:

   • Use password managers
   • Consider offline storage
   • Document recovery procedures

Key Distribution

1. Secure Methods

   • In-person exchange
   • Secure file transfer
   • Encrypted communication

2. Documentation

   • Maintain key inventory
   • Document key holders
   • Record key rotation schedule

Troubleshooting

Common Issues

1. Files Not Encrypting

   • Check .gitattributes configuration
   • Verify git-crypt initialization
   • Check file paths

2. Unlock Problems

   • Verify key integrity
   • Check GPG configuration
   • Confirm user access

Recovery Procedures

1. Lost Keys

   • Use backup symmetric key
   • Re-encrypt if necessary
   • Update team access

2. Repository Recovery

   • Clean checkout
   • Reinitialize git-crypt
   • Restore from backup