1GIT-SECRET(7) git-secret 0.4.0 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 git-se‐
30 cret repository. This can be done by running git secret add <file‐
31 names...> command. Make sure these files are ignored by mentions in
32 .gitignore, otherwise git-secret won´t allow you to add them, as
33 these files could be stored unencrypted. In the default configura‐
34 tion, git-secret add will automatically add the unencrypted ver‐
35 sions 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. Af‐
40 ter using git secret hide to encrypt your data, it is safe to com‐
41 mit your changes. NOTE: It´s recommended to add the git secret hide
42 command to your pre-commit hook, so you won´t miss any changes.
43 7. Later you can decrypt files with the git secret reveal command, or
45 just print their contents to stdout with the git secret cat com‐
46 mand. If you used a password on your GPG key (always recommended),
47 it will ask you for your password. And you´re done!
48 Usage: Adding someone to a repository using git-secret
52 1. Get their gpg public-key. You won´t need their secret key.
53 2. Import this key into your gpg keyring (in ~/.gnupg or similar) by
55 running gpg --import KEY_NAME.txt
56 3. Now add this person to your secrets repo by running git secret tell
58 persons@email.id (this will be the email address associated with
59 the public key)
60 4. The newly added user cannot yet read the encrypted files. Now,
62 re-encrypt the files using git secret reveal; git secret hide -d,
63 and then commit and push the newly encrypted files. (The -d options
64 deletes the unencrypted file after re-encrypting it). Now the newly
65 added user will be able to decrypt the files in the repo using
66 git-secret reveal.
67 Note that it is possible to add yourself to the git-secret repo without
71 decrypting existing files. It will be possible to decrypt them after
72 re-encrypting them with the new keyring. So, if you don´t want unex‐
73 pected keys added, you can configure some server-side security policy
74 with the pre-receive hook.
75 Using gpg
77 You can follow a quick gpg tutorial at devdungeon https://www.devdun‐
78 geon.com/content/gpg-tutorial. Here are the most useful commands to get
79 started:
80 To generate a RSA key-pair, run:
82 gpg --gen-key
86 To export your public key, run:
90 gpg --export your.email@address.com --armor > public-key.gpg
94 To import the public key of someone else (to share the secret with them
98 for instance), run:
99 gpg --import public-key.gpg
103 To make sure you get the original public keys of the indicated persons,
107 be sure to use a secure channel to transfer it, or use a service you
108 trust, preferably one that uses encryption such as Keybase, to retrieve
109 their public key. Otherwise you could grant the wrong person access to
110 your secrets by mistake!
111 Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)
113 When using git-secret for CI/CD, you get the benefit that any deploy‐
114 ment is necessarily done with the correct configuration, since it is
115 collocated with the changes in your code.
116 One way of doing it is the following:
118 1. create a gpg key for your CI/CD environment. You can chose any name
120 and email address you want: for instance MyApp CodeShip
121 <myapp@codeship.com> if your app is called MyApp and your CI/CD
122 provider is CodeShip. It is easier not to define a password for
123 that key.
124 2. run gpg --export-secret-key myapp@codeship.com --armor to get your
126 private key value
127 3. Create an env var on your CI/CD server GPG_PRIVATE_KEY and assign
129 it the private key value.
130 4. Then write your Continuous Deployment build script. For instance:
132 # As the first step: install git-secret,
138 # see: https://git-secret.io/installation
139 # Create private key file
141 echo $GPG_PRIVATE_KEY > ./private_key.gpg
142 # Import private key
143 gpg --import ./private_key.gpg
144 # Reveal secrets
145 git secret reveal
146 # carry on with your build script, secret files are available ...
147 Note: your CI/CD might not allow you to create a multiline value. In
151 that case, you can export it on one line with
152 gpg --export-secret-key myapp@codeship.com --armor | tr ´\n´ ´,´
156 You can then create your private key file with:
160 echo $GPG_PRIVATE_KEY | tr ´,´ ´\n´ > ./private_key.gpg
164
168 You can configure the version of gpg used, or the extension your en‐
169 crypted files use, to suit your workflow better. To do so, just set the
170 required variable to the value you need. This can be done in your shell
171 environment file or with each git-secret command. See below, or the man
172 page of git-secret for an explanation of the environment variables
173 git-secret uses.
174 The settings available to be changed are:
176 • $SECRETS_VERBOSE - sets the verbose flag to on for all git-secret
178 commands; is identical to using -v on each command that supports
179 it.
180 • $SECRETS_GPG_COMMAND - sets the gpg alternatives, defaults to gpg.
182 It can be changed to gpg, gpg2, pgp, /usr/local/gpg or any other
183 value. After doing so rerun the tests to be sure that it won´t
184 break anything. Tested to be working with: gpg, gpg2.
185 • $SECRETS_EXTENSION - sets the secret files extension, defaults to
187 .secret. It can be changed to any valid file extension.
188 • $SECRETS_DIR - sets the directory where git-secret stores its
190 files, defaults to .gitsecret. It can be changed to any valid di‐
191 rectory name.
192 • $SECRETS_PINENTRY - allows user to specify a setting for gpg´s
194 --pinentry option. See gpg docs for details about gpg´s --pinentry
195 option.
196
200 This folder contains information about the files encrypted by git-se‐
201 cret, and about which public/private key sets can access the encrypted
202 data.
203 You can change the name of this directory using the SECRETS_DIR envi‐
205 ronment variable.
206 Use the various ´git secret´ commands to manipulate the files in .git‐
208 secret, you should not change the data in these files directly.
209 Exactly which files exist in the .gitsecret folder and what their con‐
211 tents are vary slightly across different versions of gpg. Thus it is
212 best to use git-secret with the same version of gpg being used by all
213 users. This can be forced using SECRETS_GPG_COMMAND environment vari‐
214 able.
215 Specifically, there is an issue between gpg version 2.1.20 and later
217 versions which can cause problems reading and writing keyring files be‐
218 tween systems (this shows up in errors like ´gpg: skipped packet of
219 type 12 in keybox´).
220 The git-secret internal data is separated into two directories:
222 <code>.gitsecret/paths</code>
224 This directory currently contains only the file mapping.cfg, which
225 lists all the files your storing encrypted. In other words, the path
226 mappings: what files are tracked to be hidden and revealed.
227 All the other internal data is stored in the directory:
229 <code>.gitsecret/keys</code>
231 This directory contains data used by git-secret and PGP to allow and
232 maintain the correct encryption and access rights for the permitted
233 parties.
234 Generally speaking, all the files in this directory except random_seed
236 should be checked into your repo. By default, git secret init will add
237 the file .gitsecret/keys/random_seed to your .gitignore file.
238 Again, you can change the name of this directory using the SECRETS_DIR
240 environment variable.
241sobolevn May 2021 GIT-SECRET(7)