There’s a well known issue with deploying and configuring software on servers: generally you have to store your private data (such as database passwords, application secret-keys, OAuth secret keys, etc) outside of the git repository.
If you do choose to store these secrets unencrypted in your git repo, even if the repository is private, it is a security risk to copy the secrets everywhere you check out your repo.
What are some drawbacks of storing secrets separately from your git repo?
These files are not version controlled. Filenames, locations, and passwords change from time to time, or new information appears, and other information is removed. When secrets are stored separately from your repo, you can not tell for sure which version of the configuration file was used with each commit or deploy.
When building the automated deployment system there will be one extra step: download and place these secret-configuration files where they need to be. This also means you have to maintain extra secure servers where all your secrets are stored.
git-secret solve these problems?
git-secretencrypts files and stores them inside your
gitrepository, providing a history of changes for every commit.
git-secretdoesn’t require any extra deploy operations other than providing the appropriate private key (to allow decryption), and using
git secret revealto decrypt all the secret files.
git-secret is a bash tool to store your private data inside a
How’s that? Basically, it uses
gpg to encrypt files with the
public keys of the users that you trust, and which you have specified with
git secret tell firstname.lastname@example.org.
Then these users can decrypt these files using their personal secret key.
Why deal with all this private/public key stuff?
To make it easier to manage access rights.
When you want to remove someone’s access, use
git secret removeperson email@example.com
to delete their public key from your repo’s git-secret keyring, and reencrypt the files.
Then they won’t be able to decrypt secrets anymore.
git-secret - bash tool to store private data inside a git repo.
Usage: Setting up git-secret in a repository
These steps cover the basic process of using
to specify users and files that will interact with
and to encrypt and decrypt secrets.
Before starting, make sure you have created a
gpgRSA key-pair: which are a public key and a secret key pair, identified by your email address and stored with your gpg configuration. Generally this gpg configuration and keys will be stored somewhere in your home directory.
Begin with an existing or new git repository.
git-secretrepository by running
git secret init. The
.gitsecret/folder will be created, with subdirectories
.gitsecret/keys/random_seedwill be added to
.gitignorewill be configured to not ignore
Note all the contents of the
.gitsecret/ folder should be checked in, /except/ the
This also means that of all the files in
.gitsecret/, only the
random_seed file should be mentioned in your
Add the first user to the
git-secretrepo keyring by running
git secret tell firstname.lastname@example.org.
Now it’s time to add files you wish to encrypt inside the
git-secretrepository. This can be done by running
git secret add <filenames...>command, which will also (as of 0.2.6) add entries to
.gitignore, stopping those files from being be added or committed to the repo unencrypted.
git secret hideto encrypt the files you added with
git secret add. The files will be encrypted with the public keys in your git-secret repo’s keyring, each corresponding to a user’s email that you used with
git secret hide to encrypt your data, it is safe to commit your changes.
NOTE: It’s recommended to add the
git secret hide command to your
pre-commit hook, so you won’t miss any changes.
- Later you can decrypt files with the
git secret revealcommand, or print their contents to stdout with the
git secret catcommand. If you used a password on your GPG key (always recommended), it will ask you for your password. And you’re done!
Usage: Adding someone to a repository using git-secret
gpgpublic-key. You won’t need their secret key. They can export their public key for you using a command like:
gpg --armor --export email@example.com > public_key.txt # --armor here makes it ascii
Import this key into your
~/.gnupgor similar) by running
gpg --import public_key.txt
Now add this person to your secrets repo by running
git secret tell firstname.lastname@example.org(this will be the email address associated with their public key)
Now remove the other user’s public key from your personal keyring with
gpg --delete-keys email@example.com
The newly added user cannot yet read the encrypted files. Now, re-encrypt the files using
git secret reveal; git secret hide -d, and then commit and push the newly encrypted files. (The -d options deletes the unencrypted file after re-encrypting it). Now the newly added user will be able to decrypt the files in the repo using
Note that when you first add a user to a git-secret repo, they will not be able to decrypt existing files until another user re-encrypts the files with the new keyring.
If you do not
want unexpected keys added, you can configure some server-side security policy with the
You can follow a quick
gpg tutorial at devdungeon. Here are the most useful commands to get started:
To generate a RSA key-pair, run:
To export your public key, run:
gpg --armor --export firstname.lastname@example.org > public-key.gpg
To import the public key of someone else (to share the secret with them for instance), run:
gpg --import public-key.gpg
To make sure you get the original public keys of the indicated persons, be sure to use a secure channel to transfer it, or use a service you trust, preferably one that uses encryption such as Keybase, to retrieve their public key. Otherwise you could grant the wrong person access to your secrets by mistake!
Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)
git-secret for CI/CD, you get the benefit that any deployment is necessarily done with the correct configuration, since it is collocated
with the changes in your code.
One way of doing it is the following:
- create a gpg key for your CI/CD environment. You can chose any name and email address you want: for instance
MyApp Example <email@example.com>if your app is called MyApp and your CI/CD provider is Example. It is easier not to define a passphrase for that key. However, if defining a passphrase is unavoidable, use a unique passphrase for the private key.
gpg --armor --export-secret-key firstname.lastname@example.org get your private key value
- Create an env var on your CI/CD server
GPG_PRIVATE_KEYand assign it the private key value. If a passphrase has been setup for the private key, create another env var on the CI/CD server
GPG_PASSPHRASEand assign it the passphrase of the private key.
- Then write your Continuous Deployment build script. For instance:
# As the first step: install git-secret, # see: https://git-secret.io/installation # Create private key file echo "$GPG_PRIVATE_KEY" > ./private_key.gpg # Import private key and avoid the "Inappropriate ioctl for device" error gpg --batch --yes --pinentry-mode loopback --import private_key.gpg # Reveal secrets without user interaction and with passphrase. If no passphrase # is created for the key, remove `-p $GPG_PASSPHRASE` git secret reveal -p "$GPG_PASSPHRASE" # carry on with your build script, secret files are available ...
Note: your CI/CD might not allow you to create a multiline value. In that case, you can export it on one line with
gpg --armor --export-secret-key email@example.com | tr '\n' ','
You can then create your private key file with:
echo "$GPG_PRIVATE_KEY" | tr ',' '\n' > ./private_key.gpg
Also note: the
gpg version on the CI/CD server MUST INTEROPERATE with the one used locally. Otherwise,
gpg decryption can fail, which leads to
git secret reveal reporting
cannot find decrypted version of file error. The best way to ensure this is to use the same version of gnupg on different systems.
Environment Variables and Configuration
You can configure the version of
gpg used, or the extension your encrypted files use, to suit your workflow better.
To do so, just set the required variable to the value you need.
This can be done in your shell environment file or with each
See below, or the man page of
git-secret for an explanation of the environment variables
The settings available to be changed are:
$SECRETS_VERBOSE- sets the verbose flag to on for all
git-secretcommands; is identical to using
-von each command that supports it.
$SECRETS_GPG_COMMAND- sets the
gpgalternatives, defaults to
gpg. It can be changed to
/usr/local/gpgor any other value. After doing so rerun the tests to be sure that it won’t break anything. Tested with
$SECRETS_GPG_ARMOR- sets the
--armormode. Can be set to
1to store secrets file as text. By default is
0and store files as binaries.
$SECRETS_EXTENSION- sets the secret files extension, defaults to
.secret. It can be changed to any valid file extension.
$SECRETS_DIR- sets the directory where
git-secretstores its files, defaults to
.gitsecret. It can be changed to any valid directory name.
$SECRETS_PINENTRY- allows user to specify a setting for
gpgdocs for details about gpg’s
.gitsecret folder (can be overridden with
This folder contains information about the files encrypted by git-secret, and about which public/private key sets can access the encrypted data.
You can change the name of this directory using the SECRETS_DIR environment variable.
Use the various
git-secret commands to manipulate the files in
you should not change the data in these files directly.
Exactly which files exist in the
.gitsecret folder and what their contents are
vary slightly across different versions of gpg. Also, some versions of gpg
might not work well with keyrings created or modified with newer versions of gpg.
Thus it is best to use git-secret with the same version of gpg being used by all users.
This can be forced by installing matching versions of gpg
SECRETS_GPG_COMMAND environment variable.
For example, there is an issue between
gpg version 2.1.20 and later versions
which can cause problems reading and writing keyring files between systems
(this shows up in errors like ‘gpg: skipped packet of type 12 in keybox’).
This is not the only issue it is possible to encounter sharing files between different versions
Generally you are most likely to encounter issues between
versions if you use
git-secret tell or
git-secret removeperson to modify
git-secret keyring using a newer version of
gpg, and then try to operate
on that keyring using an older version of
git-secret internal data is separated into two directories:
This directory currently contains only the file
mapping.cfg, which lists all the files git-secret will consider secret.
In other words, the path mappings: what files are tracked to be hidden and revealed.
All other internal data used by git-secret is stored in the directory:
This directory contains data used by
gpg to encrypt files to
be accessed by the permitted users.
In particular, this directory contains a
gnupg keyring with public keys for the emails used with
This is the keyring used to encrypt files with
git-secret-cat, which decrypt secrets,
instead use the user’s private keys (which probably reside somewhere like ~/.gnupg/).
Note that user’s private keys, needed for decryption, are not in the
Generally speaking, all the files in this directory except
random_seed should be checked into your repo.
git secret init will add the file
.gitsecret/keys/random_seed to your
Again, you can change the name of this directory using the SECRETS_DIR environment variable.
subscribe via RSS