This post describes how to encrypt some files (containing secrets) in git repositories in a transparent way. The chosen solution encrypts files before they are pushed to the remote and decrypts it at pull locally (so you have to make sure that your secrets are well protected on your local computer).

Different tools exist to perform this task, including BlackBox, SOPS, transcrypt, git-secret. I chose git-crypt because it is available through a Ubuntu package, is really fully transparent, is well referenced, cited, and used, is regularly maintained, and can work over GnuPG.

# First step: as a maintainer, initialize your git-crypt repository

git-crypt is easily installed with apt (install gnupg if you do not have it installed already):

sudo apt install gnupg git-crypt


Locally, initialize your git repository as usual and add the git-crypt initialization afterwards:

git init
git-crypt init


Then, create a .gitattributes file including the list of files and directories that you want encrypted in your remote repository:

secretfile filter=git-crypt diff=git-crypt
*.key filter=git-crypt diff=git-crypt
secretdir/** filter=git-crypt diff=git-crypt


Note that, to include all files of a given directory secretdir/, the syntax is secretdir/** and not secretdir/*!

GnuPG users can be added by ID or email by:

 git-crypt add-gpg-user tuxette@my-domain.org 

This creates an encrypted GPG key within .git-crypt/keys, which is automatically commited.

Then, configure your remote directory (supposed, here, to be empty; this is done with git remote add ...), add and commit all the files that are supposed to be versionned, in addition to the file .gitattributes and push. Further add, commit, pull, push commands can then be used as usual.

# Second step: as a new user to an existing repository, set your git-crypt configuration

You need first to install gnupg and git-crypt with:

sudo apt install gnupg git-crypt


Then, start by generating your GPG key (if you don't have one already) with:

gpg --gen-key


Once done, you can check it with:

gpg --list-keys


that should look like:

pub   rsa4096 2016-10-31 [SC]
551C582A867ABF1865E86006378CDF2A339F144E
uid           [ultimate] Tuxette Chix <tuxette@my-domain.org>
sub   rsa4096 2016-10-31 [E]


which you can export using

gpg --armor --export 551C582A867ABF1865E86006378CDF2A339F144E > my_public_key.pub


(the ID 551C582A867ABF1865E86006378CDF2A339F144E has to be adapted to your own key). Send this file to the repository admin and waits for her/him to allow you to access the git-crypt repository.

When everything is ready, all you have to do is simply:

git clone gitolite@git.my-domain.org:my-nice-git-repo.git
git-crypt unlock


You can then add, commit, pull and push as usual.

# Second step bis: as an admin, add a new user to use secrets

When a new user sends her/his GPG key, add it to your GnuPG configuration with:

gpg --import new-public-key.pub


You can check that it has properly been added with

gpg --list-keys


You may need to "trust" the key before you can proceed. You can do it by signing it:

gpg --edit-key 551C582A867ABF1865E86006378CDF2A339F144E


then type sign, quit, and finally yes to save the edition of the key.

Finally, in the git repository, run:

git-crypt add-gpg-user <new_user_email@other-domain.org>


where the email is the one referenced in the key (you can also add a user with the key ID). Do not forget to push the changes (the new user's encrypted key)!