Archives/git-secret
2
1
Fork 0
mirror of https://github.com/sobolevn/git-secret synced 2024-11-08 19:10:31 +00:00
Code Issues Projects Releases Wiki Activity

Improve docs wording, formatting, fixes #603 part 2 (#606)

Browse Source 
* Improve docs wording, formatting, fixes #603
This commit is contained in:
teutates 2020-09-20 20:46:48 +02:00 committed by GitHub
parent 599a344644
commit 71f7891d88
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
man/man7/git-secret.7.ronn
View File

@ -5,27 +5,28 @@ git-secret - bash tool to store private data inside a git repo.
These steps cover the basic process of using `git-secret`:
0. Before starting, [make sure you have created `gpg` RSA key-pair](#using-gpg): public and secret key identified by your email address.
0. Before starting, [make sure you have created a `gpg` RSA key-pair](#using-gpg): a public and a secret key identified by your email address.
1. Begin with an existing or new git repository. You'll use the 'git secret' commands to add the keyrings and information
to make the git-secret hide and reveal files in this repository.
to make `git-secret` hide and reveal files in this repository.
2. Initialize the `git-secret` repository by running `git secret init` command. the `.gitsecret/` folder will be created,
**Note** all the contents of the `.gitsecret/` folder should be checked in, /except/ the `random_seed` file.
In other words, of the files in .gitsecret, only the random_seed file should be mentioned in your .gitignore file.
2. Initialize the `git-secret` repository by running `git secret init` command. The `.gitsecret/` folder will be created.
**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.
By default, `git secret init` will add the file `.gitsecret/keys/random_seed` to your `.gitignore` file.
3. Add the first user to the git-secret repo keyring by running `git secret tell your@gpg.email`.
3. Add the first user to the `git-secret` repo keyring by running `git secret tell your@gpg.email`.
4. Now it's time to add files you wish to encrypt inside the `git-secret` repository.
It can be done by running `git secret add <filenames...>` command. Make sure these files are ignored by mentions in
.gitignore, otherwise `git-secret` won't allow you to add them, as these files could be stored unencrypted.
This can be done by running `git secret add <filenames...>` command. Make sure these files are ignored by mentions in
`.gitignore`, otherwise `git-secret` won't allow you to add them, as these files could be stored unencrypted. In the default configuration, `git-secret add` will automatically add the unencrypted versions of the files to `.gitignore` for you.
5. When done, run `git secret hide` to encrypt all files which you have added by the `git secret add` command.
The data will be encrypted with the public-keys described by the `git secret tell` command.
After using `git secret hide` to encrypt your data, it is safe to commit your changes.
**NOTE:**. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes.
**NOTE:** It's recommended to add the `git secret hide` command to your `pre-commit` hook, so you won't miss any changes.
6. Later you can decrypt files with the `git secret reveal` command, or just show their contents to stdout with the
6. Later you can decrypt files with the `git secret reveal` command, or just print their contents to stdout with the
`git secret cat` command. If you used a password on your GPG key (always recommended), it will ask you for your password.
And you're done!
@ -33,7 +34,7 @@ And you're done!
1. [Get their `gpg` public-key](#using-gpg). **You won't need their secret key.**
2. Import this key into your `gpg` setup (in ~/.gnupg or similar) by running `gpg --import KEY_NAME.txt`
2. Import this key into your `gpg` keyring (in `~/.gnupg` or similar) by running `gpg --import KEY_NAME.txt`
3. Now add this person to your secrets repo by running `git secret tell persons@email.id`
(this will be the email address associated with the public key)
@ -41,7 +42,7 @@ And you're done!
4. The newly added user cannot yet read the encrypted files. Now, re-encrypt the files using
`git secret reveal; git secret hide -d`, and then commit and push the newly encrypted files.
(The -d options deletes the unencrypted file after re-encrypting it).
Now the newly added user be able to decrypt the files in the repo using `git-secret`.
Now the newly added user will be able to decrypt the files in the repo using `git-secret reveal`.
Note that it is possible to add yourself to the git-secret repo without decrypting existing files.
It will be possible to decrypt them after re-encrypting them with the new keyring. So, if you don't
@ -49,7 +50,7 @@ want unexpected keys added, you can configure some server-side security policy w
### Using gpg
You can follow a quick gpg tutorial at https://www.devdungeon.com/content/gpg-tutorial. Here are the most useful commands to get started:
You can follow a quick `gpg` tutorial at [devdungeon](https://www.devdungeon.com/content/gpg-tutorial). Here are the most useful commands to get started:
To generate a RSA key-pair, run:
@ -69,11 +70,11 @@ To import the public key of someone else (to share the secret with them for inst
gpg --import public-key.gpg
```
Be sure to use a secure channel to share your public key!
To make sure you get the original public keys of the indicated persons, be sure to use a secure channel to transfer it, or use a service you trust, preferably one that uses encryption such as Keybase, to retrieve their public key. Otherwise you could grant the wrong person access to your secrets by mistake!
### Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)
When using git-secret for CI/CD, you get the benefit that any deployment is necessarily done with the correct configuration, since it is collocated
When using `git-secret` for CI/CD, you get the benefit that any deployment is necessarily done with the correct configuration, since it is collocated
with the changes in your code.
One way of doing it is the following:
@ -112,9 +113,10 @@ echo $GPG_PRIVATE_KEY | tr ',' '\n' > ./private_key.gpg
## Environment Variables and Configuration
You can configure the version of gpg used, or the extension your encrypted files use, to suit your workflow better.
You can configure the version of `gpg` used, or the extension your encrypted files use, to suit your workflow better.
To do so, just set the required variable to the value you need.
This can be done in your shell environment file or with each `git-secret` command.
See below, or the man page of `git-secret` for an explanation of the environment variables `git-secret` uses.
The settings available to be changed are:
@ -166,6 +168,6 @@ All the other internal data is stored in the directory:
This directory contains data used by git-secret and PGP to allow and maintain the correct encryption and access rights for the permitted parties.
Generally speaking, all the files in this directory *except* `random_seed` should be checked into your repo.
By default, `git secret init` will add the file `.gitsecret/keys/random_seed` to your .gitignore file.
By default, `git secret init` will add the file `.gitsecret/keys/random_seed` to your `.gitignore` file.
Again, you can change the name of this directory using the SECRETS_DIR environment variable.