How to create encrypted git repositories with git-remote-gcrypt

Git is, by far, the most used version control system. Being it “distributed”, means that each user can clone its own full copy of a repository on which he can work even if offline, pushing changes to a remote only when ready. Git repositories are not designed to host sensitive information, but in certain situations, the ability of transparently encrypt the content of a repository can come in handy. The git remote-gcrypt helper is designed with this goal in mind.

In this tutorial we see how to install and use git-remote-gcrypt on some of the most used Linux distributions and how to use it to create encrypted git repositories.

In this tutorial you will learn:

  • How to install git-remote-gcrypt
  • How to setup an encrypted git repository with git-remote-gcrypt
How to create encrypted git repositories with git-remote-gcrypt
How to create encrypted git repositories with git-remote-gcrypt


Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Distribution-agnostic
Software git-remote-gcrypt
Other a gpg keypair
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command
$ – requires given linux-commands to be executed as a regular non-privileged user


Git-remote-gcrypt is basically a bash script, itself developed on github; it is packaged and available in the repositories of the most used Linux distributions, together with GPG, which it uses to encrypt data. Both packages can be installed using your favorite distribution’s package manager. on Fedora, for example, we would use dnf:

$ sudo dnf install git-remote-gcrypt gpg

To install the package on Debian, or one of its many derivatives, instead, we would run:

$ sudo apt install git-remote-gcrypt gpg

Creating an encrypted repository

To start working with git-remote-gcrypt, as a first thing, we create a local repository (let’s call it “test-git-remote-gcrypt”), and switch into it:

$ git init test-git-remote-gcrypt && cd test-git-remote-gcrypt

Now we need to create a repository to use as a remote. For the sake of this tutorial I will create one on Github (it doesn’t matter if its public or private):

Creating a git repository on Github
Creating a repository on Github

At this point we need to add the repository we created on Github as a remote. The procedure is the same we always use; the only thing we need to change is the URL of the remote which we need to prefix with the gcrypt:: notation (in the example below I used ssh to communicate with the remote, but the same thing is valid for “https”):

$ git remote add origin

Specifying a GPG keypair for encryption

We are almost done. Now we need to specify the GPG public key which should be used to encrypt data. Here I will assume you already have a keypair available, however, if you are not familiar with GPG, you can learn how to generate one by reading this guide.

To specify the keypair we want to use, we need to issue the following command, from the local repository directory:

$ git config remote.<remote>.gcrypt-participants <gpg-public-key-fingerprint>

Where, of course, “<remote>” is a placeholder for the name of the remote (“origin”, in this case), and <gpg-public-key-fingerprint> must be substituted by the fingerprint of the public key(s) we want to use. Multiple fingerprints can be specified (space separated, between quotes), to let multiple users with different keys access the repository.

In order to retrieve the fingerprint of a public key, we can simply run the following command:

$ gpg --list-keys

That is basically all. Now we can create a dummy file, stage it, commit the change and push to the remote repository:

$ touch dummyfile
$ git add dummyfile
$ git commit -m "first commit"
$ git push origin master

At this point we will be asked to provide the passphrase to unlock our GPG secret key in order to decrypt the manifest, which must be updated at each push to make sure it contains the fingerprints of the public keys of all participants. Finally the changes will be pushed to the remote.

If we now take a look at the content of the remote repository, we will see it’s content is encrypted:

the encrypted content in the remote git repository
The encrypted content in the git remote repository

One important thing to be aware of, is that each time we push to the remote repository the --force option is used, therefore we risk loosing remote commits. In order to avoid this, we should always pull before pushing.

Closing thoughts

In this tutorial we learned how to create encrypted git repositories using the git-remote-gcrypt helper. Although you should simply avoid putting sensitive information in git repositories, especially if hosted on external, untrusted platforms, sometimes being able to transparently push encrypted content to a repository can come in handy. One of those situations that comes to mind, for example, is the use of pass: this password manager has the advantage of managing passwords using standard tools like GPG (for encryption) and git (for synchronization), however has a “weak” point in the fact that passwords are stored in files which should have meaningful names, thus potentially exposing metadata (e.g. you have your encrypted password stored in a file with the name of the site the password is for: this effectively reveals you do have an account on that platform). Please take a look at the manpage of git-remote-gcrypt to check the complete list of the options you can use with the helper.