1GIT-SECRET(7) git-secret 0.3.3 GIT-SECRET(7)
2
6 git-secret - bash tool to store private data inside a git repo.
7
9 These steps cover the basic process of using git-secret:
10 1. Before starting, make sure you have created a gpg RSA key-pair: a
12 public and a secret key identified by your email address.
13 2. Begin with an existing or new git repository. You´ll use the ´git
15 secret´ commands to add the keyrings and information to make
16 git-secret hide and reveal files in this repository.
17 3. Initialize the git-secret repository by running git secret init
19 command. The .gitsecret/ folder will be created. Note all the con‐
20 tents of the .gitsecret/ folder should be checked in, /except/ the
21 random_seed file. In other words, of all the files in .gitsecret/,
22 only the random_seed file should be mentioned in your .gitignore
23 file. By default, git secret init will add the file .gitse‐
24 cret/keys/random_seed to your .gitignore file.
25 4. Add the first user to the git-secret repo keyring by running git
27 secret tell your@gpg.email.
28 5. Now it´s time to add files you wish to encrypt inside the
30 git-secret repository. This can be done by running git secret add
31 <filenames...> command. Make sure these files are ignored by men‐
32 tions in .gitignore, otherwise git-secret won´t allow you to add
33 them, as these files could be stored unencrypted. In the default
34 configuration, git-secret add will automatically add the unen‐
35 crypted versions of the files to .gitignore for you.
36 6. When done, run git secret hide to encrypt all files which you have
38 added by the git secret add command. The data will be encrypted
39 with the public-keys described by the git secret tell command.
40 After using git secret hide to encrypt your data, it is safe to
41 commit your changes. NOTE: It´s recommended to add the git secret
42 hide command to your pre-commit hook, so you won´t miss any
43 changes.
44 7. Later you can decrypt files with the git secret reveal command, or
46 just print their contents to stdout with the git secret cat com‐
47 mand. If you used a password on your GPG key (always recommended),
48 it will ask you for your password. And you´re done!
49 Usage: Adding someone to a repository using git-secret
53 1. Get their gpg public-key. You won´t need their secret key.
54 2. Import this key into your gpg keyring (in ~/.gnupg or similar) by
56 running gpg --import KEY_NAME.txt
57 3. Now add this person to your secrets repo by running git secret tell
59 persons@email.id (this will be the email address associated with
60 the public key)
61 4. The newly added user cannot yet read the encrypted files. Now,
63 re-encrypt the files using git secret reveal; git secret hide -d,
64 and then commit and push the newly encrypted files. (The -d options
65 deletes the unencrypted file after re-encrypting it). Now the newly
66 added user will be able to decrypt the files in the repo using
67 git-secret reveal.
68 Note that it is possible to add yourself to the git-secret repo without
72 decrypting existing files. It will be possible to decrypt them after
73 re-encrypting them with the new keyring. So, if you don´t want unex‐
74 pected keys added, you can configure some server-side security policy
75 with the pre-receive hook.
76 Using gpg
78 You can follow a quick gpg tutorial at devdungeon https://www.devdun‐
79 geon.com/content/gpg-tutorial. Here are the most useful commands to get
80 started:
81 To generate a RSA key-pair, run:
83 gpg --gen-key
87 To export your public key, run:
91 gpg --export your.email@address.com --armor > public-key.gpg
95 To import the public key of someone else (to share the secret with them
99 for instance), run:
100 gpg --import public-key.gpg
104 To make sure you get the original public keys of the indicated persons,
108 be sure to use a secure channel to transfer it, or use a service you
109 trust, preferably one that uses encryption such as Keybase, to retrieve
110 their public key. Otherwise you could grant the wrong person access to
111 your secrets by mistake!
112 Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)
114 When using git-secret for CI/CD, you get the benefit that any deploy‐
115 ment is necessarily done with the correct configuration, since it is
116 collocated with the changes in your code.
117 One way of doing it is the following:
119 1. create a gpg key for your CI/CD environment. You can chose any name
121 and email address you want: for instance MyApp CodeShip
122 <myapp@codeship.com> if your app is called MyApp and your CI/CD
123 provider is CodeShip. It is easier not to define a password for
124 that key.
125 2. run gpg --export-secret-key myapp@codeship.com --armor to get your
127 private key value
128 3. Create an env var on your CI/CD server GPG_PRIVATE_KEY and assign
130 it the private key value.
131 4. Then write your Continuous Deployment build script. For instance:
133 # Install git-secret (https://git-secret.io/installation), for instance, for debian:
139 echo "deb https://dl.bintray.com/sobolevn/deb git-secret main" | sudo tee -a /etc/apt/sources.list
140 wget -qO - https://api.bintray.com/users/sobolevn/keys/gpg/public.key | sudo apt-key add -
141 sudo apt-get update && sudo apt-get install git-secret
142 # Create private key file
143 echo $GPG_PRIVATE_KEY > ./private_key.gpg
144 # Import private key
145 gpg --import ./private_key.gpg
146 # Reveal secrets
147 git secret reveal
148 # carry on with your build script, secret files are available ...
149 Note: your CI/CD might not allow you to create a multiline value. In
153 that case, you can export it on one line with
154 gpg --export-secret-key myapp@codeship.com --armor | tr ´\n´ ´,´
158 You can then create your private key file with:
162 echo $GPG_PRIVATE_KEY | tr ´,´ ´\n´ > ./private_key.gpg
166
170 You can configure the version of gpg used, or the extension your
171 encrypted files use, to suit your workflow better. To do so, just set
172 the required variable to the value you need. This can be done in your
173 shell environment file or with each git-secret command. See below, or
174 the man page of git-secret for an explanation of the environment vari‐
175 ables git-secret uses.
176 The settings available to be changed are:
178 · $SECRETS_VERBOSE - sets the verbose flag to on for all git-secret
180 commands; is identical to using -v on each command that supports
181 it.
182 · $SECRETS_GPG_COMMAND - sets the gpg alternatives, defaults to gpg.
184 It can be changed to gpg, gpg2, pgp, /usr/local/gpg or any other
185 value. After doing so rerun the tests to be sure that it won´t
186 break anything. Tested to be working with: gpg, gpg2.
187 · $SECRETS_EXTENSION - sets the secret files extension, defaults to
189 .secret. It can be changed to any valid file extension.
190 · $SECRETS_DIR - sets the directory where git-secret stores its
192 files, defaults to .gitsecret. It can be changed to any valid
193 directory name.
194 · $SECRETS_PINENTRY - allows user to specify a setting for gpg´s
196 --pinentry option. See gpg docs for details about gpg´s --pinentry
197 option.
198
202 This folder contains information about the files encrypted by
203 git-secret, and about which public/private key sets can access the
204 encrypted data.
205 You can change the name of this directory using the SECRETS_DIR envi‐
207 ronment variable.
208 Use the various ´git secret´ commands to manipulate the files in .git‐
210 secret, you should not change the data in these files directly.
211 Exactly which files exist in the .gitsecret folder and what their con‐
213 tents are vary slightly across different versions of gpg. Thus it is
214 best to use git-secret with the same version of gpg being used by all
215 users. This can be forced using SECRETS_GPG_COMMAND environment vari‐
216 able.
217 Specifically, there is an issue between gpg version 2.1.20 and later
219 versions which can cause problems reading and writing keyring files
220 between systems (this shows up in errors like ´gpg: skipped packet of
221 type 12 in keybox´).
222 The git-secret internal data is separated into two directories:
224 <code>.gitsecret/paths</code>
226 This directory currently contains only the file mapping.cfg, which
227 lists all the files your storing encrypted. In other words, the path
228 mappings: what files are tracked to be hidden and revealed.
229 All the other internal data is stored in the directory:
231 <code>.gitsecret/keys</code>
233 This directory contains data used by git-secret and PGP to allow and
234 maintain the correct encryption and access rights for the permitted
235 parties.
236 Generally speaking, all the files in this directory except random_seed
238 should be checked into your repo. By default, git secret init will add
239 the file .gitsecret/keys/random_seed to your .gitignore file.
240 Again, you can change the name of this directory using the SECRETS_DIR
242 environment variable.
243sobolevn November 2020 GIT-SECRET(7)