more doc improvements (#848)

pull/852/head
Josh Rabinowitz 2 years ago committed by GitHub
parent c143bf0652
commit 38379a2aee
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -1,44 +1,46 @@
## Intro
There's a well-known problem in deploying and configuring software on servers,
where you generally have to store your private data
There's a well known issue with deploying and configuring software on servers:
generally you have to store your private data
(such as database passwords, application secret-keys, OAuth secret keys, etc)
outside of the git repository.
If you do choose to store these secrets unencrypted in your git repo,
even if the repository is private, it is a security risk to just copy
these secrets everywhere you check out your repo.
even if the repository is private, it is a security risk to copy
the secrets everywhere you check out your repo.
What are some drawbacks of storing secrets separately from your git repo?
1. These files are not version controlled.
Filenames, locations, and passwords change from time to time;
or some new information appears, and other information is removed.
Filenames, locations, and passwords change from time to time,
or new information appears, and other information is removed.
When secrets are stored separately from your repo,
you can not tell for sure which version of the configuration file was used with each commit
or deploy.
2. When building the automated deployment system there will be one extra step:
download and place these secret-configuration files where they need to be.
So you have to maintain _extra_ secure servers, where all your secrets are stored.
This also means you have to maintain extra secure servers where all your secrets are stored.
### How does `git-secret` solve these problems?
1. `git-secret` encrypts files and stores them inside the `git` repository, so you will have all the changes for every commit.
2. `git-secret` doesn't require any other deploy operations other than providing the appropriate
private key (to allow decryption), and using `git secret reveal`,
to automatically decrypt all the secret files.
1. `git-secret` encrypts files and stores them inside your `git` repository, providing a history of changes for every commit.
2. `git-secret` doesn't require any extra deploy operations other than providing the appropriate
private key (to allow decryption), and using `git secret reveal`
to decrypt all the secret files.
### What is `git-secret`?
`git-secret` is a bash tool to store your private data inside a `git` repo.
How's that? Basically, it encrypts, using `gpg`, the tracked files with the
public keys of all the users that you trust (and which you have specified with
`git secret tell email@address.id`.
Then permitted users can decrypt these files using only their personal secret key.
Why deal with all this private-public keys stuff?
How's that? Basically, it uses `gpg` to encrypt files with the
public keys of the users that you trust, and which you have specified with
`git secret tell email@address.id`.
Then these users can decrypt these files using their personal secret key.
Why deal with all this private/public key stuff?
To make it easier to manage access rights.
When you want to remove someone's access, use `git secret removeperson email@address.id`
to delete their public key from your repo's git-secret keyring, and reencrypt the files.

@ -21,7 +21,7 @@ Initialize the \fBgit\-secret\fR repository by running \fBgit secret init\fR\. T
.IP "" 0
.
.P
\fBNote\fR all the contents of the \fB\.gitsecret/\fR folder should be checked in, \fB/except/\fR the \fBrandom_seed\fR file\. In other words, of all the files in \fB\.gitsecret/\fR, only the \fBrandom_seed\fR file should be mentioned in your \fB\.gitignore\fR file\.
\fBNote\fR all the contents of the \fB\.gitsecret/\fR folder should be checked in, \fB/except/\fR the \fBrandom_seed\fR file\. This also means that of all the files in \fB\.gitsecret/\fR, only the \fBrandom_seed\fR file should be mentioned in your \fB\.gitignore\fR file\.
.
.IP "1." 4
Add the first user to the \fBgit\-secret\fR repo keyring by running \fBgit secret tell your@email\.id\fR\.
@ -49,15 +49,8 @@ Later you can decrypt files with the \fBgit secret reveal\fR command, or print t
.
.IP "" 0
.
.IP "" 4
.
.nf
gpg \-\-armor \-\-export their@email\.com > public_key\.txt # armor here makes it ascii
.
.fi
.
.IP "" 0
.P
\fBgpg \-\-armor \-\-export their@email\.com > public_key\.txt\fR \fB# armor here makes it ascii\fR
.
.IP "1." 4
Import this key into your \fBgpg\fR keyring (in \fB~/\.gnupg\fR or similar) by running \fBgpg \-\-import public_key\.txt\fR
@ -171,7 +164,7 @@ Note: your CI/CD might not allow you to create a multiline value\. In that case,
.
.nf
gpg \-\-armor \-\-export\-secret\-key myapp@codeship\.com | tr \'\en\' \',\'
gpg \-\-armor \-\-export\-secret\-key myapp@example\.com | tr \'\en\' \',\'
.
.fi
.

@ -20,7 +20,7 @@ with subdirectories `keys/` and `paths/`,
and `.gitignore` will be configured to _not_ ignore `.secret` files.
**Note** all the contents of the `.gitsecret/` folder should be checked in, **/except/** the `random_seed` file.
In other words, of all the files in `.gitsecret/`, only the `random_seed` file should be mentioned in your `.gitignore` file.
This also means that of all the files in `.gitsecret/`, only the `random_seed` file should be mentioned in your `.gitignore` file.
3. Add the first user to the `git-secret` repo keyring by running `git secret tell your@email.id`.
@ -44,9 +44,8 @@ And you're done!
1. [Get their `gpg` public-key](#using-gpg). **You won't need their secret key.**
They can export their public key for you using a command like:
```shell
gpg --armor --export their@email.com > public_key.txt # armor here makes it ascii
```
`gpg --armor --export their@email.com > public_key.txt`
`# armor here makes it ascii`
2. Import this key into your `gpg` keyring (in `~/.gnupg` or similar) by running `gpg --import public_key.txt`
@ -120,7 +119,7 @@ git secret reveal -p "$GPG_PASSPHRASE"
Note: your CI/CD might not allow you to create a multiline value. In that case, you can export it on one line with
```shell
gpg --armor --export-secret-key myapp@codeship.com | tr '\n' ','
gpg --armor --export-secret-key myapp@example.com | tr '\n' ','
```
You can then create your private key file with:

Loading…
Cancel
Save