mirror of https://github.com/sobolevn/git-secret
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
220 lines
9.0 KiB
Groff
220 lines
9.0 KiB
Groff
.\" generated with Ronn/v0.7.3
|
|
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
|
.
|
|
.TH "GIT\-SECRET" "7" "March 2020" "sobolevn" "git-secret 0.3.2"
|
|
.
|
|
.SH "NAME"
|
|
\fBgit\-secret\fR \- bash tool to store private data inside a git repo\.
|
|
.
|
|
.SH "Usage: Setting up git\-secret in a repository"
|
|
These steps cover the basic process of using \fBgit\-secret\fR:
|
|
.
|
|
.IP "1." 4
|
|
Before starting, \fImake sure you have created \fBgpg\fR RSA key\-pair\fR: public and secret key identified by your email address\.
|
|
.
|
|
.IP "2." 4
|
|
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\.
|
|
.
|
|
.IP "3." 4
|
|
Initialize the \fBgit\-secret\fR repository by running \fBgit secret init\fR command\. the \fB\.gitsecret/\fR folder will be created, \fBNote\fR all the contents of the \fB\.gitsecret/\fR folder should be checked in, /except/ the \fBrandom_seed\fR file\. In other words, of the files in \.gitsecret, only the random_seed file should be mentioned in your \.gitignore file\.
|
|
.
|
|
.IP "4." 4
|
|
Add the first user to the git\-secret repo keyring by running \fBgit secret tell your@gpg\.email\fR\.
|
|
.
|
|
.IP "5." 4
|
|
Now it\'s time to add files you wish to encrypt inside the \fBgit\-secret\fR repository\. It can be done by running \fBgit secret add <filenames\.\.\.>\fR command\. Make sure these files are ignored by mentions in \.gitignore, otherwise \fBgit\-secret\fR won\'t allow you to add them, as these files could be stored unencrypted\.
|
|
.
|
|
.IP "6." 4
|
|
When done, run \fBgit secret hide\fR to encrypt all files which you have added by the \fBgit secret add\fR command\. The data will be encrypted with the public\-keys described by the \fBgit secret tell\fR command\. After using \fBgit secret hide\fR to encrypt your data, it is safe to commit your changes\. \fBNOTE:\fR\. It\'s recommended to add \fBgit secret hide\fR command to your \fBpre\-commit\fR hook, so you won\'t miss any changes\.
|
|
.
|
|
.IP "7." 4
|
|
Later you can decrypt files with the \fBgit secret reveal\fR command, or just show their contents to stdout with the \fBgit secret cat\fR command\. If you used a password on your GPG key (always recommended), it will ask you for your password\. And you\'re done!
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SS "Usage: Adding someone to a repository using git\-secret"
|
|
.
|
|
.IP "1." 4
|
|
\fIGet their \fBgpg\fR public\-key\fR\. \fBYou won\'t need their secret key\.\fR
|
|
.
|
|
.IP "2." 4
|
|
Import this key into your \fBgpg\fR setup (in ~/\.gnupg or similar) by running \fBgpg \-\-import KEY_NAME\.txt\fR
|
|
.
|
|
.IP "3." 4
|
|
Now add this person to your secrets repo by running \fBgit secret tell persons@email\.id\fR (this will be the email address associated with the public key)
|
|
.
|
|
.IP "4." 4
|
|
The newly added user cannot yet read the encrypted files\. Now, re\-encrypt the files using \fBgit secret reveal; git secret hide \-d\fR, 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 \fBgit\-secret\fR\.
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
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 \fBpre\-receive\fR hook\.
|
|
.
|
|
.SS "Using gpg"
|
|
You can follow a quick gpg tutorial at https://www\.devdungeon\.com/content/gpg\-tutorial\. Here are the most useful commands to get started:
|
|
.
|
|
.P
|
|
To generate a RSA key\-pair, run:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
gpg \-\-gen\-key
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
To export your public key, run:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
gpg \-\-export your\.email@address\.com \-\-armor > public\-key\.gpg
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
To import the public key of someone else (to share the secret with them for instance), run:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
gpg \-\-import public\-key\.gpg
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Be sure to use a secure channel to share your public key!
|
|
.
|
|
.SS "Using git\-secret for Continuous Integration / Continuous Deployment (CI/CD)"
|
|
When using 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\.
|
|
.
|
|
.P
|
|
One way of doing it is the following:
|
|
.
|
|
.IP "1." 4
|
|
\fIcreate a gpg key\fR for your CI/CD environment\. You can chose any name and email address you want: for instance \fBMyApp CodeShip <myapp@codeship\.com>\fR if your app is called MyApp and your CI/CD provider is CodeShip\. It is easier not to define a password for that key\.
|
|
.
|
|
.IP "2." 4
|
|
run \fBgpg \-\-export\-secret\-key myapp@codeship\.com \-\-armor\fR to get your private key value
|
|
.
|
|
.IP "3." 4
|
|
Create an env var on your CI/CD server \fBGPG_PRIVATE_KEY\fR and assign it the private key value\.
|
|
.
|
|
.IP "4." 4
|
|
Then write your Continuous Deployment build script\. For instance:
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
# Install git\-secret (https://git\-secret\.io/installation), for instance, for debian:
|
|
echo "deb https://dl\.bintray\.com/sobolevn/deb git\-secret main" | sudo tee \-a /etc/apt/sources\.list
|
|
wget \-qO \- https://api\.bintray\.com/users/sobolevn/keys/gpg/public\.key | sudo apt\-key add \-
|
|
sudo apt\-get update && sudo apt\-get install git\-secret
|
|
# Create private key file
|
|
echo $GPG_PRIVATE_KEY > \./private_key\.gpg
|
|
# Import private key
|
|
gpg \-\-import \./private_key\.gpg
|
|
# Reveal secrets
|
|
git secret reveal
|
|
# carry on with your build script, secret files are available \.\.\.
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Note: your CI/CD might not allow you to create a multiline value\. In that case, you can export it on one line with
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
gpg \-\-export\-secret\-key myapp@codeship\.com \-\-armor | tr \'\en\' \',\'
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
You can then create your private key file with:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
echo $GPG_PRIVATE_KEY | tr \',\' \'\en\' > \./private_key\.gpg
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SH "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 \fBgit\-secret\fR command\.
|
|
.
|
|
.P
|
|
The settings available to be changed are:
|
|
.
|
|
.IP "\(bu" 4
|
|
\fB$SECRETS_VERBOSE\fR \- sets the verbose flag to on for all \fBgit\-secret\fR commands; is identical to using \fB\-v\fR on each command that supports it\.
|
|
.
|
|
.IP "\(bu" 4
|
|
\fB$SECRETS_GPG_COMMAND\fR \- sets the \fBgpg\fR alternatives, defaults to \fBgpg\fR\. It can be changed to \fBgpg\fR, \fBgpg2\fR, \fBpgp\fR, \fB/usr/local/gpg\fR or any other value\. After doing so rerun the tests to be sure that it won\'t break anything\. Tested to be working with: \fBgpg\fR, \fBgpg2\fR\.
|
|
.
|
|
.IP "\(bu" 4
|
|
\fB$SECRETS_EXTENSION\fR \- sets the secret files extension, defaults to \fB\.secret\fR\. It can be changed to any valid file extension\.
|
|
.
|
|
.IP "\(bu" 4
|
|
\fB$SECRETS_DIR\fR \- sets the directory where git\-secret stores its files, defaults to \.gitsecret\. It can be changed to any valid directory name\.
|
|
.
|
|
.IP "\(bu" 4
|
|
\fB$SECRETS_PINENTRY\fR \- allows user to specify a setting for \fBgpg\fR\'s \-\-pinentry option\. See \fBgpg\fR docs for details about gpg\'s \-\-pinentry option\.
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SH "The <code>\.gitsecret</code> 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\.
|
|
.
|
|
.P
|
|
You can change the name of this directory using the SECRETS_DIR environment variable\.
|
|
.
|
|
.P
|
|
Use the various \'git secret\' commands to manipulate the files in \fB\.gitsecret\fR, you should not change the data in these files directly\.
|
|
.
|
|
.P
|
|
Exactly which files exist in the \fB\.gitsecret\fR 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\.
|
|
.
|
|
.P
|
|
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\')\.
|
|
.
|
|
.P
|
|
The git\-secret internal data is separated into two directories:
|
|
.
|
|
.SS "<code>\.gitsecret/paths</code>"
|
|
This directory currently contains only the file \fBmapping\.cfg\fR, which lists all the files your storing encrypted\. In other words, the path mappings: what files are tracked to be hidden and revealed\.
|
|
.
|
|
.P
|
|
All the other internal data is stored in the directory:
|
|
.
|
|
.SS "<code>\.gitsecret/keys</code>"
|
|
This directory contains data used by git\-secret and PGP to allow and maintain the correct encryption and access rights for the permitted parties\.
|
|
.
|
|
.P
|
|
Generally speaking, all the files in this directory \fIexcept\fR \fBrandom_seed\fR should be checked into your repo\. By default, \fBgit secret init\fR will add the file \fB\.gitsecret/keys/random_seed\fR to your \.gitignore file\.
|
|
.
|
|
.P
|
|
Again, you can change the name of this directory using the SECRETS_DIR environment variable\.
|