1GIT-SECRET(7)                  git-secret 0.3.3                  GIT-SECRET(7)
2
3
4

NAME

6       git-secret - bash tool to store private data inside a git repo.
7

Usage: Setting up git-secret in a repository

9       These steps cover the basic process of using git-secret:
10
11       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
14       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
18       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
26       4.  Add the first user to the git-secret repo keyring  by  running  git
27           secret tell your@gpg.email.
28
29       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
37       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
45       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
50
51
52   Usage: Adding someone to a repository using git-secret
53       1.  Get their gpg public-key. You won´t need their secret key.
54
55       2.  Import this key into your gpg keyring (in ~/.gnupg or  similar)  by
56           running gpg --import KEY_NAME.txt
57
58       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
62       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
69
70
71       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
77   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
82       To generate a RSA key-pair, run:
83
84
85
86           gpg --gen-key
87
88
89
90       To export your public key, run:
91
92
93
94           gpg --export your.email@address.com --armor > public-key.gpg
95
96
97
98       To import the public key of someone else (to share the secret with them
99       for instance), run:
100
101
102
103           gpg --import public-key.gpg
104
105
106
107       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
113   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
118       One way of doing it is the following:
119
120       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
126       2.  run  gpg --export-secret-key myapp@codeship.com --armor to get your
127           private key value
128
129       3.  Create an env var on your CI/CD server GPG_PRIVATE_KEY  and  assign
130           it the private key value.
131
132       4.  Then write your Continuous Deployment build script. For instance:
133
134
135
136
137
138           # 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
150
151
152       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
155
156
157           gpg --export-secret-key myapp@codeship.com --armor | tr ´\n´ ´,´
158
159
160
161       You can then create your private key file with:
162
163
164
165           echo $GPG_PRIVATE_KEY | tr ´,´ ´\n´ > ./private_key.gpg
166
167
168

Environment Variables and Configuration

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
177       The settings available to be changed are:
178
179       ·   $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
183       ·   $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
188       ·   $SECRETS_EXTENSION - sets the secret files extension,  defaults  to
189           .secret. It can be changed to any valid file extension.
190
191       ·   $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
195       ·   $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
199
200

The <code>.gitsecret</code> folder (can be overridden with SECRETS_DIR)

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
206       You  can  change the name of this directory using the SECRETS_DIR envi‐
207       ronment variable.
208
209       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
212       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
218       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
223       The git-secret internal data is separated into two directories:
224
225   <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
230       All the other internal data is stored in the directory:
231
232   <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
237       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
241       Again, you can change the name of this directory using the  SECRETS_DIR
242       environment variable.
243
244
245
246sobolevn                         November 2020                   GIT-SECRET(7)
Impressum