Git Secret Tutorial

git-secret is a tool to encrypt files. It helps you to give another person access to this file and to remove the access again. So it helps to keep secrets confidential and share the secrets between authorized people. Without such a tool you would need to keep the secrets out of your version control system and share them in a separate channel. This way takes a lot of effort especially if you add, remove or change a secret. A none secure way would be to push your secrets directly into git. The secrets are visible to everyone, who has access to your repository and if your repository becomes public for some reason everyone gets the secrets.

git-secret is used in combination with git. This brings the advantage that your secrets are version controlled and any change in your secrets is confidentially distributed to the members of the repository. Another advantage is, that your continuous deployment (CD) system can also get access to the encrypted file. So you don’t need to have a separate system for your secrets.

There are also some drawbacks, which you should be aware of

  • git-secret does not support Windows systems (at least not yet). A workaround would be to use Linux subsystem in Windows.
  • The nature of git-secret is to encrypt files not lines in the file. This leads to the issue that if you have a merge conflict in git you have to fix them in collaboration with your teammate. There is no special part, which can be merged.
  • You have to decrypt and encrypt the secret file for every new user who gets access. It’s not sufficient to add the public key.

Enough introduction let’s start with the tutorial. I will show you how to configure git-secret on a Debian system. Before we can start with git-secret we need to install three packages:

sudo apt-get install git gnupg git-secret

You need the GnuPG package to create the key pair. This is the basis for git-secret, which is used to allow other people access to the encrypted file. Git is needed as a version control system and git-secret as an encryption tool to hide the secrets. The next step is to create the key pair:

gpg --gen-key

Add your name and your mail address to get the key pair. The next steps show you how to create a git repository and add a file with secrets. We initialize git-secret and add our user. Before we can encrypt a file, the file has to be in the .gitignore file. Otherwise, the file will not be encrypted by git-secret. The last commands encrypt the secret file and decrypt it.

# Create a folder for our repository
$ mkdir test_repo
$ cd test_repo

# Initialize empty git repository
$ git init .

# Create a file and add some secret
$ touch
$ echo "secret.key=secret.value" >>

# Initialize git-secret
$ git secret init

# Add the first user to git-secret
$ git secret tell

# Add secret file to .gitignore
$ echo "" >> .gitignore 

# Add secret file
$ git secret add

# Encrypt secret file
$ git secret hide

# Delete secret file
$ rm

# Decrypt secret file
$ git secret reveal

Now we created the basis git-secret to share our secret with other people. Every new user needs also a gpg key. The snippet shows what he has to do to get one:

# B creates gpg key
$ gpg --gen-key

# B exports public key
$ gpg --export --armor > public-key-b.gpg

User B has to transfer the public key to a member who is already signed to git-secret. Let’s call the signed user: User A. User A has to import the public key of User B. Then he needs to re-encrypt the file. Otherwise, User B does not have access to the file.

# Import public key of B
$ gpg --import public-key-b.gpg

# Add B to git secret
git secret tell

# Re-encrypt the file to make it available for B
$ git secret reveal
$ git secret hide -d // -d deletes the file after the command is done

# Push changes to origin
$ git add --all
$ git commit -m "Add B to git secret"
$ git push

To get access to the file User B has to pull the changes from the origin and he can decrypt the file.

# Pull changes from origin
$ git pull

# B can decrypt the file 
$ git secret reveal

It is also possible to set up your CI/CD system. So you can deploy your application and deliver decrypted secrets. this is out of the scope of this article, but you can visit the official page and get more information. There exist also other tools like git-crypt or transcrypt but I don’t have experience with them, yet. Let me comment if you like git-secret for some reason or not. If not I would like to know which tool you use and why 🙂


Leave a comment

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.