1GIT-SECRET(7) git-secret GIT-SECRET(7)
2
6 git-secret
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_GPG_COMMAND - sets the gpg alternatives, defaults to gpg.
82 It can be changed to gpg, gpg2, pgp, /usr/local/gpg or any other
83 value. After doing so rerun the tests to be sure that it won´t
84 break anything. Tested to be working with: gpg, gpg2.
85 · $SECRETS_EXTENSION - sets the secret files extension, defaults to
87 .secret. It can be changed to any valid file extension.
88 · $SECRETS_DIR - sets the directory where git-secret stores its
90 files, defaults to .gitsecret. It can be changed to any valid
91 directory name.
92
96 This folder contains information about the files encrypted by
97 git-secret, and about which public/private key sets can access the
98 encrypted data.
99 You can change the name of this directory using the SECRETS_DIR envi‐
101 ronment variable.
102 Use the various ´git secret´ commands to manipulate the files in .git‐
104 secret, you should not change the data in these files directly.
105 Exactly which files exist in the .gitsecret folder and what their con‐
107 tents are vary slightly across different versions of gpg. Thus it is
108 best to use git-secret with the same version of gpg being used by all
109 users. This can be forced using SECRETS_GPG_COMMAND environment vari‐
110 able.
111 Specifically, there is an issue between gpg version 2.1.20 and later
113 versions which can cause problems reading and writing keyring files
114 between systems (this shows up in errors like ´gpg: skipped packet of
115 type 12 in keybox´).
116 The git-secret internal data is separated into two directories:
118 <code>.gitsecret/paths</code>
120 This directory currently contains only the file mapping.cfg, which
121 lists all the files your storing encrypted. In other words, the path
122 mappings: what files are tracked to be hidden and revealed.
123 All the other internal data is stored in the directory:
125 <code>.gitsecret/keys</code>
127 This directory contains data used by git-secret and PGP to allow and
128 maintain the correct encryption and access rights for the permitted
129 parties.
130 Generally speaking, all the files in this directory except random_seed
132 should be checked into your repo.
133 By default, git secret init will add the file .gitsecret/keys/ran‐
134 dom_seed to your .gitignore file.
135 Again, you can change the name of this directory using the SECRETS_DIR
137 environment variable.
138sobolevn August 2018 GIT-SECRET(7)