1GIT-SECRET(7) git-secret 0.3.2 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 gpg RSA key-pair: pub‐
12 lic and 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 the
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 the files in .gitsecret, only
22 the random_seed file should be mentioned in your .gitignore file.
23 4. Add the first user to the git-secret repo keyring by running git
25 secret tell your@gpg.email.
26 5. Now it´s time to add files you wish to encrypt inside the
28 git-secret repository. It can be done by running git secret add
29 <filenames...> command. Make sure these files are ignored by men‐
30 tions in .gitignore, otherwise git-secret won´t allow you to add
31 them, as these files could be stored unencrypted.
32 6. When done, run git secret hide to encrypt all files which you have
34 added by the git secret add command.
35 The data will be encrypted with the public-keys described by the
36 git secret tell command. After using git secret hide to encrypt
37 your data, it is safe to commit your changes. NOTE:. It´s recom‐
38 mended to add git secret hide command to your pre-commit hook, so
39 you won´t miss any changes.
40 7. Later you can decrypt files with the git secret reveal command, or
42 just show their contents to stdout with the git secret cat command.
43 If you used a password on your GPG key (always recommended), it
44 will ask you for your password. And you´re done!
45 Usage: Adding someone to a repository using git-secret
49 1. Get their gpg public-key. You won´t need their secret key.
50 2. Import this key into your gpg setup (in ~/.gnupg or similar) by
52 running gpg --import KEY_NAME.txt
53 3. Now add this person to your secrets repo by running git secret tell
55 persons@email.id (this will be the email address associated with
56 the public key)
57 4. The newly added user cannot yet read the encrypted files. Now,
59 re-encrypt the files using git secret reveal; git secret hide -d,
60 and then commit and push the newly encrypted files. (The -d options
61 deletes the unencrypted file after re-encrypting it). Now the newly
62 added user be able to decrypt the files in the repo using
63 git-secret.
64 Note that it is possible to add yourself to the git-secret repo without
68 decrypting existing files. It will be possible to decrypt them after
69 re-encrypting them with the new keyring. So, if you don´t want unex‐
70 pected keys added, you can configure some server-side security policy
71 with the pre-receive hook.
72
74 You can configure the version of gpg used, or the extension your
75 encrypted files use, to suit your workflow better. To do so, just set
76 the required variable to the value you need. This can be done in your
77 shell environment file or with each git-secret command.
78 The settings available to be changed are:
80 · $SECRETS_VERBOSE - sets the verbose flag to on for all git-secret
82 commands; is identical to using -v on each command that supports
83 it.
84 · $SECRETS_GPG_COMMAND - sets the gpg alternatives, defaults to gpg.
86 It can be changed to gpg, gpg2, pgp, /usr/local/gpg or any other
87 value. After doing so rerun the tests to be sure that it won´t
88 break anything. Tested to be working with: gpg, gpg2.
89 · $SECRETS_EXTENSION - sets the secret files extension, defaults to
91 .secret. It can be changed to any valid file extension.
92 · $SECRETS_DIR - sets the directory where git-secret stores its
94 files, defaults to .gitsecret. It can be changed to any valid
95 directory name.
96 · $SECRETS_PINENTRY - allows user to specify a setting for gpg´s
98 --pinentry option. See gpg docs for details about gpg´s --pinentry
99 option.
100
104 This folder contains information about the files encrypted by
105 git-secret, and about which public/private key sets can access the
106 encrypted data.
107 You can change the name of this directory using the SECRETS_DIR envi‐
109 ronment variable.
110 Use the various ´git secret´ commands to manipulate the files in .git‐
112 secret, you should not change the data in these files directly.
113 Exactly which files exist in the .gitsecret folder and what their con‐
115 tents are vary slightly across different versions of gpg. Thus it is
116 best to use git-secret with the same version of gpg being used by all
117 users. This can be forced using SECRETS_GPG_COMMAND environment vari‐
118 able.
119 Specifically, there is an issue between gpg version 2.1.20 and later
121 versions which can cause problems reading and writing keyring files
122 between systems (this shows up in errors like ´gpg: skipped packet of
123 type 12 in keybox´).
124 The git-secret internal data is separated into two directories:
126 <code>.gitsecret/paths</code>
128 This directory currently contains only the file mapping.cfg, which
129 lists all the files your storing encrypted. In other words, the path
130 mappings: what files are tracked to be hidden and revealed.
131 All the other internal data is stored in the directory:
133 <code>.gitsecret/keys</code>
135 This directory contains data used by git-secret and PGP to allow and
136 maintain the correct encryption and access rights for the permitted
137 parties.
138 Generally speaking, all the files in this directory except random_seed
140 should be checked into your repo.
141 By default, git secret init will add the file .gitsecret/keys/ran‐
142 dom_seed to your .gitignore file.
143 Again, you can change the name of this directory using the SECRETS_DIR
145 environment variable.
146sobolevn September 2019 GIT-SECRET(7)