git-crypt is an extension to the Git Source code management software (Private) that allows securing secrets stored in versioned files. It's useful in operations teams for storing bootstrapping credentials.


Linux users, use a package manager.

On macOS:

brew install git-crypt

Initialising a repository

First, generate a key:

git-crypt init

Then list the files you'd like encrypted in the .gitattributes file:

*.secure.tfvars filter=git-crypt diff=git-crypt

Note the filter effect, which configures git-crypt's clean and smudge commands to be executed on checkin and checkout.

Checking file status

Ensure that files are in the expected state:

$ git-crypt status
not encrypted:

Adding contributors

First, the key must exist in the GPG trust DB; see importing instructions in gnupg (Private).

To add a key:

git-crypt add-gpg-user 'Name <email>'

You can also use just an email address, or a key ID. This will commit the key under /.git-crypt/keys for later authentication.

Unlocking repositories

git-crypt supports unlocking both with a symmetric key or with GPG keys.

After checking in the changed files and pushing them, have the user on the other end fetch, then try unlocking:

git-crypt unlock

The symmetric key can be exported from an unlocked repository:

git-crypt export-key out.key.bin

Then used on locked copy:

git-crypt unlock out.key.bin


In continuous delivery settings it'll be necessary to automate unlocking the repository to read the contents of encrypted files. To achieve this, you'll need to generate a keypair and make it available to the automation pipeline in some secure way, e.g. via a "secret" environment variable. As many mechanisms will corrupt the contents (e.g. by stripping newlines), base64 encoding the keys can be useful.

Assuming the keys are made accessible as environment variables:

# Decode the PGP secret key (encoded in base64 in the secret variables to
# preserve special characters, like newlines), import it into the GnuPG
# keyring and delete it from the filesystem to minimise risk of compromise.
# Install git-crypt, and unlock the repository.
base64 -d <<<"$GIT_CRYPT_PGPKEY_PUBLIC" >public.key
base64 -d <<<"$GIT_CRYPT_PGPKEY_PRIVATE" >private.key
gpg --import public.key
gpg --import private.key
rm -f public.key private.key

sudo apt-get install -y git-crypt
git-crypt unlock