How to Install and Use git-crypt in Linux to Encrypt Sensitive Files in Git Repositories

Modern DevOps and software development practices frequently involve repositories that house a mixture of public source code and confidential assets, such as environment variables, private SSL certificates, database credentials, and proprietary configuration files. While storing unencrypted secrets in version control creates severe security liabilities, git-crypt offers a transparent, elegant solution in Linux by automatically encrypting designated files upon commit and decrypting them seamlessly upon checkout.

How git-crypt Secures Repositories

git-crypt operates by integrating directly into Git’s native filter mechanism using clean and smudge filters defined in a repository’s .gitattributes file. When an engineer commits changes to a sensitive file, git-crypt’s clean filter encrypts the file before it enters the Git staging area. Conversely, when checking out a branch, the smudge filter decrypts the content into working memory using an encryption key.

Key advantages of git-crypt include:

• Transparent Workflow: Developers edit files normally using standard text editors. No manual encryption or decryption commands are needed during day-to-day coding.
• Graceful Degradation: Contributors who do not possess the repository’s cryptographic key can still clone, review public code, and submit pull requests without corrupting encrypted files.
• Multiple Authentication Methods: Repositories can be secured using a symmetric shared secret key or asymmetric GPG (GNU Privacy Guard) public keys for granular team access management.

Installing git-crypt on Linux Distributions

git-crypt is available directly through the package managers of major Linux distributions or can be compiled from source.

For Debian, Ubuntu, and Linux Mint systems, install via apt:

sudo apt update && sudo apt install -y git-crypt

For Fedora, RHEL, and CentOS Stream:

sudo dnf install -y git-crypt

For Arch Linux and Manjaro:

sudo pacman -S git-crypt

Verify successful installation and check the binary version by running:

git-crypt --version

Initialising and Configuring a Repository with Symmetric Keys

The simplest method to secure a repository is by generating a standalone symmetric key file that can be distributed securely to authorized team members.

Step 1: Initialise git-crypt in the Target Repository

Navigate to your local Git repository and run the initialisation command:

cd ~/projects/my-secure-app
git-crypt init

This command creates internal cryptographic state tracking within the .git/git-crypt directory and configures Git filters.

Step 2: Export the Symmetric Secret Key

To ensure you can decrypt the repository on another machine or share access with a colleague, export the secret key to a secure location outside the repository:

git-crypt export-key /path/to/secure_storage/my-repo.key

Security Warning: Never commit the exported .key file into the Git repository itself. Store it in a secure password manager or encrypted vault.

Step 3: Define Encrypted Files in .gitattributes

Create or open the .gitattributes file in the repository root to specify which files or directory patterns must be encrypted:

nano .gitattributes

Add patterns designating sensitive files, applying the filter=git-crypt and diff=git-crypt attributes:

# Encrypt specific environment configurations
.env filter=git-crypt diff=git-crypt
secrets.json filter=git-crypt diff=git-crypt

# Encrypt entire sensitive directories
config/credentials/* filter=git-crypt diff=git-crypt
certs/*.pem filter=git-crypt diff=git-crypt

# Ensure .gitattributes itself remains unencrypted
.gitattributes !filter !diff

Step 4: Commit and Verify Encryption Status

Commit your configuration to Git:

git add .gitattributes
git commit -m "Configure git-crypt attribute filters"

To verify which files are protected before pushing to remote repositories, run the status diagnostic:

git-crypt status

The command lists tracked files, marking sensitive targets as encrypted and non-sensitive files as not encrypted.

Cloning and Unlocking Repositories on New Systems

When a repository protected with git-crypt is cloned on a fresh Linux workstation, encrypted files initially appear as raw binary ciphertext:

1. Clone the remote repository normally:

   git clone [email protected]:example/my-secure-app.git
   cd my-secure-app

2. Unlock the files using your exported symmetric key:

   git-crypt unlock /path/to/secure_storage/my-repo.key

git-crypt verifies the key against the repository’s cryptographic manifest and instantly decrypts all matching files into plaintext in the working directory.

Managing Team Access with GPG Keys

For organisations with multiple developers, managing shared symmetric keys can lead to key rotation headaches when staff depart. git-crypt natively supports GPG public-key cryptography:

Command	Operational Function
git-crypt add-gpg-user <GPG_KEY_ID>	Adds an individual collaborator’s public key to the repository’s allowed list
git-crypt unlock	Unlocks the repository using the local user’s GPG private key without needing an external key file
git-crypt lock	Re-locks working tree files into encrypted state for testing or security lockdown

When using GPG, run git-crypt add-gpg-user GPG_USER_ID. git-crypt automatically encrypts a copy of the repository key with the specified GPG public key and commits the manifest under .git-crypt/keys/. Collaborators can then simply run git-crypt unlock, and their local GPG agent handles decryption seamlessly.