1GIT-SECRET(7)                  git-secret 0.4.0                  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 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
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. 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
44       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
49
50
51   Usage: Adding someone to a repository using git-secret
52       1.  Get their gpg public-key. You won´t need their secret key.
53
54       2.  Import  this  key into your gpg keyring (in ~/.gnupg or similar) by
55           running gpg --import KEY_NAME.txt
56
57       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
61       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
68
69
70       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
76   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
81       To generate a RSA key-pair, run:
82
83
84
85           gpg --gen-key
86
87
88
89       To export your public key, run:
90
91
92
93           gpg --export your.email@address.com --armor > public-key.gpg
94
95
96
97       To import the public key of someone else (to share the secret with them
98       for instance), run:
99
100
101
102           gpg --import public-key.gpg
103
104
105
106       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
112   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
117       One way of doing it is the following:
118
119       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
125       2.  run gpg --export-secret-key myapp@codeship.com --armor to get  your
126           private key value
127
128       3.  Create  an  env var on your CI/CD server GPG_PRIVATE_KEY and assign
129           it the private key value.
130
131       4.  Then write your Continuous Deployment build script. For instance:
132
133
134
135
136
137           # As the first step: install git-secret,
138           # see: https://git-secret.io/installation
139
140           # 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
148
149
150       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
153
154
155           gpg --export-secret-key myapp@codeship.com --armor | tr ´\n´ ´,´
156
157
158
159       You can then create your private key file with:
160
161
162
163           echo $GPG_PRIVATE_KEY | tr ´,´ ´\n´ > ./private_key.gpg
164
165
166

Environment Variables and Configuration

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
175       The settings available to be changed are:
176
177$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
181$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
186$SECRETS_EXTENSION  -  sets the secret files extension, defaults to
187           .secret. It can be changed to any valid file extension.
188
189$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
193$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
197
198

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

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
204       You can change the name of this directory using the  SECRETS_DIR  envi‐
205       ronment variable.
206
207       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
210       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
216       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
221       The git-secret internal data is separated into two directories:
222
223   <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
228       All the other internal data is stored in the directory:
229
230   <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
235       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
239       Again,  you can change the name of this directory using the SECRETS_DIR
240       environment variable.
241
242
243
244sobolevn                           May 2021                      GIT-SECRET(7)
Impressum