Encrypting some files in git repositories with git-crypt
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
GnuPG users can be added by ID or email by:
git-crypt add-gpg-user email@example.com
This creates an encrypted GPG key within
.git-crypt/keys, which is automatically commited.
More information on GnuPG is available at this page (unfortunately in French).
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:
Once done, you can check it with:
that should look like:
pub rsa4096 2016-10-31 [SC] 551C582A867ABF1865E86006378CDF2A339F144E uid [ultimate] Tuxette Chix <firstname.lastname@example.org> sub rsa4096 2016-10-31 [E]
which you can export using
gpg --armor --export 551C582A867ABF1865E86006378CDF2A339F144E > my_public_key.pub
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 email@example.com: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
You may need to "trust" the key before you can proceed. You can do it by signing it:
gpg --edit-key 551C582A867ABF1865E86006378CDF2A339F144E
quit, and finally
yes to save the edition of the key.
Finally, in the git repository, run:
git-crypt add-gpg-user <firstname.lastname@example.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)!