DevOps Blog

A Beginner's Guide to `git-secret`: Keep Your Secrets Safe in Git

What is git-secret?

git-secret is an open-source tool that:

  1. Encrypts files using GPG before they're committed to Git
  2. Only allows authorized team members to decrypt the files
  3. Works seamlessly with your existing Git workflow

It's perfect for storing things like:

  • Database credentials
  • API keys
  • Configuration files with sensitive data
  • SSL certificates

Installation

First, you'll need to install git-secret and its dependencies.

On macOS (using Homebrew):

brew install git-secret gnupg

On Linux (Debian/Ubuntu):

sudo apt-get install git-secret gnupg

On Windows (using WSL or Chocolatey):

choco install git-secret

Setting Up git-secret in Your Repository

Step 1: Initialize git-secret

Navigate to your Git repository and run:

git secret init

This creates a .gitsecret directory that will store encryption keys and configuration.

Step 2: Add Team Members

Before adding secrets, you need to specify who can access them. Each team member needs a GPG key.

To add yourself:

gpg --gen-key # If you don't have a GPG key yet gpg --list-keys # Find your key ID git secret tell your@email.com

To add another team member, have them send you their public key, then:

gpg --import team-member.pub git secret tell team@member.com

Using git-secret

Adding Secrets

Let's say you have a file config.ini with sensitive data that you want to protect:

  1. Add the file to git-secret:
git secret add config.ini
  1. The file is now in .gitsecret/paths/mapping.cfg but not yet encrypted.

Encrypting Secrets

To encrypt all files you've added:

git secret hide

This creates an encrypted version of each file with .secret appended (e.g., config.ini.secret).

Committing Encrypted Files

Now you can safely commit the encrypted files:

git add config.ini.secret git commit -m "Add encrypted config file"

Make sure to add *.secret to your .gitignore file to prevent accidentally committing unencrypted versions.

Decrypting Secrets

When you or a team member needs to access the secrets:

git secret reveal

This decrypts all files to their original names and locations.

Best Practices

  1. Never commit unencrypted secrets: Double-check your .gitignore to exclude the original files.
  2. Rotate keys regularly: If someone leaves the team, remove their access with git secret killperson old@member.com.
  3. Use separate keys for production and development: Consider having different GPG keys for different environments.
  4. Document the process: Make sure your team knows how to use git-secret by adding instructions to your README.

Advanced Usage

Automating Encryption

Add a pre-commit hook to ensure secrets are always encrypted before committing:

echo "git secret hide" > .git/hooks/pre-commit chmod +x .git/hooks/pre-commit

Viewing Encrypted Files

To see which files are being tracked by git-secret:

git secret list

Removing Files

To stop tracking a file:

git secret remove config.ini

Conclusion

git-secret provides a simple yet powerful way to protect sensitive data in your Git repositories. By following this guide, you can securely share configuration files and credentials with your team without exposing them in your version control history.

Remember that security is an ongoing process - regularly review who has access to your secrets and keep your encryption keys safe.

Happy (and secure) coding!