There’s a known problem in server configuration and deploying, when you have to store your private data such as: database passwords, application secret-keys, OAuth secret keys and so on, outside of the git repository. Even if this repository is private, it is a security risk to just publish them into the world wide web. What are the drawbacks of storing them separately?
- These files are not version controlled. Filenames change, locations change, passwords change from time to time, some new information appears, other is removed. And you can not tell for sure which version of the configuration file was used with each commit.
- When building the automated deployment system there will be one extra step: download and place these secret-configuration files where they need to be. So you have to maintain an extra secure server, where everything is stored.
git-secret solve these problems?
git-secretencrypts files and stores them inside the
gitrepository, so you will have all the changes for every commit.
git-secretdoesn’t require any other deploy operations rather than
git secret reveal, so it will automatically decrypt all the required files.
git-secret is a bash tool to store your private data inside a
git repo. How’s that? Basically, it just encrypts, using
gpg, the tracked files with the public keys of all the users that you trust. So everyone of them can decrypt these files using only their personal secret key. Why deal with all this private-public keys stuff? Well, to make it easier for everyone to manage access rights. There are no passwords that change. When someone is out - just delete their public key, reencrypt the files, and 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
Before starting, make sure you have created
gpgRSA key-pair: public and secret key identified by your email address.
Begin with an existing or new git repository. You’ll use the ‘git secret’ commands to add the keyrings and information to make the git-secret hide and reveal files in this repository.
git-secretrepository by running
git secret initcommand. the
.gitsecret/folder will be created, Note all the contents of the
.gitsecret/folder should be checked in, /except/ the
random_seedfile. In other words, of the files in .gitsecret, only the random_seed file should be mentioned in your .gitignore file.
Add the first user to the git-secret repo 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. It can be done by running
git secret add <filenames...>command. Make sure these files are ignored by mentions in .gitignore, otherwise
git-secretwon’t allow you to add them, as these files could be stored unencrypted.
When done, run
git secret hideto encrypt all files which you have added by the
git secret addcommand.
The data will be encrypted with the public-keys described by the
git secret tellcommand. After using
git secret hideto encrypt your data, it is safe to commit your changes. NOTE:. It’s recommended to add
git secret hidecommand to your
pre-commithook, so you won’t miss any changes.
Later you can decrypt files with the
git secret revealcommand, or just show 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.
Import this key into your
gpgsetup (in ~/.gnupg or similar) by running
gpg --import KEY_NAME.txt
Now add this person to your secrets repo by running
git secret tell email@example.com(this will be the email address associated with the public key)
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 be able to decrypt the files in the repo using
Note that it is possible to add yourself to the git-secret repo without decrypting existing files.
It will be possible to decrypt them after re-encrypting them with the new keyring. So, if you don’t
want unexpected keys added, you can configure some server-side security policy with the
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
The settings available to be changed are:
$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 to be working with:
$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-secret stores its files, defaults to .gitsecret. It can be changed to any valid directory name.
.gitsecret folder (can be overridden with SECRETS_DIR)
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. Thus it is best to use
git-secret with the same version of gpg being used by all users.
This can be forced using SECRETS_GPG_COMMAND environment variable.
Specifically, 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’).
The git-secret internal data is separated into two directories:
This directory currently contains only the file
mapping.cfg, which lists all the files your storing encrypted.
In other words, the path mappings: what files are tracked to be hidden and revealed.
All the other internal data is stored in the directory:
This directory contains data used by git-secret and PGP to allow and maintain the correct encryption and access rights for the permitted parties.
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 .gitignore file.
Again, you can change the name of this directory using the SECRETS_DIR environment variable.
subscribe via RSS