1GIT-SECRET(7) git-secret 0.5.0-alpha2 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 to specify
10 users and files that will interact with git-secret, and to encrypt and
11 decrypt secrets.
12 1. Before starting, make sure you have created a gpg RSA key-pair:
14 which are a public key and a secret key pair, identified by your
15 email address and stored with your gpg configuration. Generally
16 this gpg configuration and keys will be stored somewhere in your
17 home directory.
18 2. Begin with an existing or new git repository.
20 3. Initialize the git-secret repository by running git secret init.
22 The .gitsecret/ folder will be created, with subdirectories keys/
23 and paths/, .gitsecret/keys/random_seed will be added to .gitig‐
24 nore, and .gitignore will be configured to not ignore .secret
25 files.
26 Note all the contents of the .gitsecret/ folder should be checked in,
30 /except/ the random_seed file. This also means that of all the files in
31 .gitsecret/, only the random_seed file should be mentioned in your
32 .gitignore file.
33 1. Add the first user to the git-secret repo keyring by running git
35 secret tell your@email.id.
36 2. Now it´s time to add files you wish to encrypt inside the git-se‐
38 cret repository. This can be done by running git secret add <file‐
39 names...> command, which will also (as of 0.2.6) add entries to
40 .gitignore, stopping those files from being be added or committed
41 to the repo unencrypted.
42 3. Then run git secret hide to encrypt the files you added with git
44 secret add. The files will be encrypted with the public keys in
45 your git-secret repo´s keyring, each corresponding to a user´s
46 email that you used with tell.
47 After using git secret hide to encrypt your data, it is safe to commit
51 your changes. NOTE: It´s recommended to add the git secret hide command
52 to your pre-commit hook, so you won´t miss any changes.
53 1. Later you can decrypt files with the git secret reveal command, or
55 print their contents to stdout with the git secret cat command. If
56 you used a password on your GPG key (always recommended), it will
57 ask you for your password. And you´re done!
58 Usage: Adding someone to a repository using git-secret
62 1. Get their gpg public-key. You won´t need their secret key. They can
63 export their public key for you using a command like:
64 gpg --armor --export their@email.com > public_key.txt # armor here
68 makes it ascii
69 1. Import this key into your gpg keyring (in ~/.gnupg or similar) by
71 running gpg --import public_key.txt
72 2. Now add this person to your secrets repo by running git secret tell
74 their@email.id (this will be the email address associated with
75 their public key)
76 3. Now remove the other user´s public key from your personal keyring
78 with gpg --delete-keys their@email.id
79 4. The newly added user cannot yet read the encrypted files. Now,
81 re-encrypt the files using git secret reveal; git secret hide -d,
82 and then commit and push the newly encrypted files. (The -d options
83 deletes the unencrypted file after re-encrypting it). Now the newly
84 added user will be able to decrypt the files in the repo using
85 git-secret reveal.
86 Note that when you first add a user to a git-secret repo, they will not
90 be able to decrypt existing files until another user re-encrypts the
91 files with the new keyring.
92 If you do not want unexpected keys added, you can configure some
94 server-side security policy with the pre-receive hook.
95 Using gpg
97 You can follow a quick gpg tutorial at devdungeon https://www.devdun‐
98 geon.com/content/gpg-tutorial. Here are the most useful commands to get
99 started:
100 To generate a RSA key-pair, run:
102 gpg --gen-key
106 To export your public key, run:
110 gpg --armor --export your.email@address.com > public-key.gpg
114 To import the public key of someone else (to share the secret with them
118 for instance), run:
119 gpg --import public-key.gpg
123 To make sure you get the original public keys of the indicated persons,
127 be sure to use a secure channel to transfer it, or use a service you
128 trust, preferably one that uses encryption such as Keybase, to retrieve
129 their public key. Otherwise you could grant the wrong person access to
130 your secrets by mistake!
131 Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)
133 When using git-secret for CI/CD, you get the benefit that any deploy‐
134 ment is necessarily done with the correct configuration, since it is
135 collocated with the changes in your code.
136 One way of doing it is the following:
138 1. create a gpg key for your CI/CD environment. You can chose any name
140 and email address you want: for instance MyApp Example <myapp@exam‐
141 ple.com> if your app is called MyApp and your CI/CD provider is Ex‐
142 ample. It is easier not to define a passphrase for that key. How‐
143 ever, if defining a passphrase is unavoidable, use a unique
144 passphrase for the private key.
145 2. run gpg --armor --export-secret-key myapp@example.com to get your
147 private key value
148 3. Create an env var on your CI/CD server GPG_PRIVATE_KEY and assign
150 it the private key value. If a passphrase has been setup for the
151 private key, create another env var on the CI/CD server
152 GPG_PASSPHRASE and assign it the passphrase of the private key.
153 4. Then write your Continuous Deployment build script. For instance:
155 # As the first step: install git-secret,
161 # see: https://git-secret.io/installation
162 # Create private key file
164 echo "$GPG_PRIVATE_KEY" > ./private_key.gpg
165 # Import private key and avoid the "Inappropriate ioctl for device" error
166 gpg --batch --yes --pinentry-mode loopback --import private_key.gpg
167 # Reveal secrets without user interaction and with passphrase. If no passphrase
168 # is created for the key, remove `-p $GPG_PASSPHRASE`
169 git secret reveal -p "$GPG_PASSPHRASE"
170 # carry on with your build script, secret files are available ...
171 Note: your CI/CD might not allow you to create a multiline value. In
175 that case, you can export it on one line with
176 gpg --armor --export-secret-key myapp@example.com | tr ´\n´ ´,´
180 You can then create your private key file with:
184 echo "$GPG_PRIVATE_KEY" | tr ´,´ ´\n´ > ./private_key.gpg
188 Also note: the gpg version on the CI/CD server MUST INTEROPERATE with
192 the one used locally. Otherwise, gpg decryption can fail, which leads
193 to git secret reveal reporting cannot find decrypted version of file
194 error. The best way to ensure this is to use the same version of gnupg
195 on different systems.
196
198 You can configure the version of gpg used, or the extension your en‐
199 crypted files use, to suit your workflow better. To do so, just set the
200 required variable to the value you need. This can be done in your shell
201 environment file or with each git-secret command. See below, or the man
202 page of git-secret for an explanation of the environment variables
203 git-secret uses.
204 The settings available to be changed are:
206 • $SECRETS_VERBOSE - sets the verbose flag to on for all git-secret
208 commands; is identical to using -v on each command that supports
209 it.
210 • $SECRETS_GPG_COMMAND - sets the gpg alternatives, defaults to gpg.
212 It can be changed to gpg, gpg2, pgp, /usr/local/gpg or any other
213 value. After doing so rerun the tests to be sure that it won´t
214 break anything. Tested with gpg and gpg2.
215 • $SECRETS_GPG_ARMOR - sets the gpg --armor mode
217 https://www.gnupg.org/gph/en/manual/r1290.html. Can be set to 1 to
218 store secrets file as text. By default is 0 and store files as bi‐
219 naries.
220 • $SECRETS_EXTENSION - sets the secret files extension, defaults to
222 .secret. It can be changed to any valid file extension.
223 • $SECRETS_DIR - sets the directory where git-secret stores its
225 files, defaults to .gitsecret. It can be changed to any valid di‐
226 rectory name.
227 • $SECRETS_PINENTRY - allows user to specify a setting for gpg´s
229 --pinentry option. See gpg docs https://github.com/gpg/pinentry for
230 details about gpg´s --pinentry option.
231
235 CRETS_DIR</code>)
236 This folder contains information about the files encrypted by git-se‐
237 cret, and about which public/private key sets can access the encrypted
238 data.
239 You can change the name of this directory using the SECRETS_DIR envi‐
241 ronment variable.
242 Use the various git-secret commands to manipulate the files in .gitse‐
244 cret, you should not change the data in these files directly.
245 Exactly which files exist in the .gitsecret folder and what their con‐
247 tents are vary slightly across different versions of gpg. Also, some
248 versions of gpg might not work well with keyrings created or modified
249 with newer versions of gpg. Thus it is best to use git-secret with the
250 same version of gpg being used by all users. This can be forced by in‐
251 stalling matching versions of gpg and using SECRETS_GPG_COMMAND envi‐
252 ronment variable.
253 For example, there is an issue between gpg version 2.1.20 and later
255 versions which can cause problems reading and writing keyring files be‐
256 tween systems (this shows up in errors like ´gpg: skipped packet of
257 type 12 in keybox´).
258 This is not the only issue it is possible to encounter sharing files
260 between different versions of gpg. Generally you are most likely to en‐
261 counter issues between gpg versions if you use git-secret tell or
262 git-secret removeperson to modify your repo´s git-secret keyring using
263 a newer version of gpg, and then try to operate on that keyring using
264 an older version of gpg.
265 The git-secret internal data is separated into two directories:
267 <code>.gitsecret/paths</code>
269 This directory currently contains only the file mapping.cfg, which
270 lists all the files your storing encrypted. In other words, the path
271 mappings: what files are tracked to be hidden and revealed.
272 All the other internal data is stored in the directory:
274 <code>.gitsecret/keys</code>
276 This directory contains data used by git-secret and gpg to encrypt
277 files to be accessed by the permitted users.
278 In particular, this directory contains a gnupg keyring with public keys
280 for the emails used with tell.
281 This is the keyring used to encrypt files with git-secret-hide.
283 git-secret-reveal and git-secret-cat, which decrypt secrets, instead
285 use the user´s private keys (which probably reside somewhere like
286 ~/.gnupg/). Note that user´s private keys, needed for decryption, are
287 not in the .gitsecret/keys directory.
288 Generally speaking, all the files in this directory except random_seed
290 should be checked into your repo. By default, git secret init will add
291 the file .gitsecret/keys/random_seed to your .gitignore file.
292 Again, you can change the name of this directory using the SECRETS_DIR
294 environment variable.
295sobolevn April 2022 GIT-SECRET(7)