From: Jessica Wagantall Date: Wed, 7 Mar 2018 21:23:07 +0000 (-0800) Subject: Add signing details for commits X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=38db5f12c516c36cea99d2486fc446f52f351f84;p=releng%2Fdocs.git Add signing details for commits - Prerequisites before using Gerrit - Signing Gerrit Commits - Generating the GPG key - Install gpg - Adding your key to Gerrit - Set up Git to sign commits - Commit and push a change Change-Id: I8ebe6615ead80608e9256e782e63de1302c856ad Issue-ID: RELENG-556 Signed-off-by: Jessica Wagantall --- diff --git a/docs/_static/gerrit-signed-push.png b/docs/_static/gerrit-signed-push.png new file mode 100644 index 0000000..b76d019 Binary files /dev/null and b/docs/_static/gerrit-signed-push.png differ diff --git a/docs/_static/gpg-setup.example b/docs/_static/gpg-setup.example new file mode 100644 index 0000000..bc33493 --- /dev/null +++ b/docs/_static/gpg-setup.example @@ -0,0 +1,22 @@ +brew install gpg2 # If you don't have homebrew, get that here: http://brew.sh/ +gpg2 --gen-key +# pick 1 for "RSA and RSA" +# enter 4096 to creat a 4096-bit key +# enter an expiration time, I picked 2y for 2 years +# enter y to accept the expiration time +# pick O or Q to accept your name/email/comment +# enter a pass phrase twice. it seems like backspace doesn't work, so type carefully +gpg2 --fingerprint +# you'll get something like this: +# spectre:~ ckd$ gpg2 --fingerprint +# /Users/ckd/.gnupg/pubring.gpg +# ----------------------------- +# pub 4096R/F566C9B1 2015-04-06 [expires: 2017-04-05] +# Key fingerprint = 7C37 02AC D651 1FA7 9209 48D3 5DD5 0C4B F566 C9B1 +# uid [ultimate] Colin Dixon +# sub 4096R/DC1497E1 2015-04-06 [expires: 2017-04-05] +# you're looking for the part after 4096R, which is your key ID +gpg2 --send-keys $KEY_ID +# in the above example, the $KEY_ID would be F566C9B1 +# you should see output like this: +# gpg: sending key F566C9B1 to hkp server keys.gnupg.net \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 7ec6e88..4d16e6a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,4 +26,5 @@ linkcheck_ignore = [ 'https://gerrit.linuxfoundation.org/infra/#/settings/http-password', 'https://jenkins.acumos.org.*', 'https://.*.example.org.*', + 'https://git.opendaylight.org/gerrit/#/settings/gpg-keys', ] diff --git a/docs/gerrit.rst b/docs/gerrit.rst index 8feca45..e0cf0f2 100644 --- a/docs/gerrit.rst +++ b/docs/gerrit.rst @@ -15,6 +15,33 @@ occur around the code commits. Here is more information on `Gerrit `_ +Prerequisites +============= + +Before you get started, you should have: + +* an LFID account (sign up `here + `_) +* git installed (see: http://www.git-scm.com/downloads) +* git configured with your name, e-mail address and editor + + .. code-block:: bash + + git config --global user.name "Firstname Lastname" + git config --global user.email "email@address.com" + git config --global core.editor "text-editor-name" + + .. note:: Your name and e-mail address (including capitalization) must match what you entered + when creating your LFID account. + +* an ssh public/private key pair (see the good `GitHub docs on generating ssh keys + `_) + + * register in the Gerrit server. See below for detailed instructions. + :ref:`register-key-gerrit` + +* git-review installed (see: https://www.mediawiki.org/wiki/Gerrit/git-review#Installation) + Clone the code ============== @@ -533,6 +560,8 @@ For a system running Ubuntu operating system, follow the steps below: Your public key is now available as **.ssh/id\_rsa.pub** in your home folder. +.. _register-key-gerrit: + Register your SSH key with Gerrit --------------------------------- @@ -661,6 +690,115 @@ repository. git review -v -s +Signing Gerrit Commits +====================== + +1. Generate your GPG key. + + The following instructions work on a Mac, but the general approach + should be the same on other OSes. + + .. literalinclude:: _static/gpg-setup.example + + If you are collaborating in keysigning, then send the output of + ``gpg2 --fingerprint $KEY_ID`` to your coworkers. + + .. code-block:: bash + + gpg2 --fingerprint $KEY_ID + # in the above example, the $KEY_ID would be F566C9B1 + # in my case, the output was: + # pub 4096R/F566C9B1 2015-04-06 [expires: 2017-04-05] + # Key fingerprint = 7C37 02AC D651 1FA7 9209 48D3 5DD5 0C4B F566 C9B1 + # uid [ultimate] Colin Dixon + # sub 4096R/DC1497E1 2015-04-06 [expires: 2017-04-05] + +2. Install gpg, instead of or addition to gpg2. + + .. note:: you can tell Git to use gpg by doing: + ``git config --global gpg.program gpg2`` + but that then will seem to struggle asking for your + passphrase unless you have your gpg-agent set up right. + +3. Add you GPG to Gerrit + + a. Run the following at the CLI: + + .. code-block:: bash + + gpg --export -a $FINGER_PRINT + # e.g., gpg --export -a F566C9B1 + # in my case the output looked like: + # -----BEGIN PGP PUBLIC KEY BLOCK----- + # Version: GnuPG v2 + # + # mQINBFUisGABEAC/DkcjNUhxQkRLdfbfdlq9NlfDusWri0cXLVz4YN1cTUTF5HiW + # ... + # gJT+FwDvCGgaE+JGlmXgjv0WSd4f9cNXkgYqfb6mpji0F3TF2HXXiVPqbwJ1V3I2 + # NA+l+/koCW0aMReK + # =A/ql + # -----END PGP PUBLIC KEY BLOCK----- + + b. Browse to https://git.opendaylight.org/gerrit/#/settings/gpg-keys + c. Click Add Key... + d. Copy the output from the above command, paste it into the box, + and click Add + +4. Set up your Git to sign commits and push signatures + + .. code-block:: bash + + git config commit.gpgsign true + git config push.gpgsign true + git config user.signingkey $FINGER_PRINT + # e.g., git config user.signingkey F566C9B1 + + .. note:: + + We can create a signed commit with ``git commit -S`` and + a signed push with ``git push --signed`` on the CLI instead of + configuring it in config if we want to manually control which commits + use the signature. + +5. Create a signed commit + + a. Change a file + b. Create a signed commit with ``git commit -asm "test commit"`` + + This will result in Git asking you for your passphrase. + Enter it to proceed. + +6. Push to Gerrit with a signed-push with ``git review`` + + This will result in Git asking you for your passphrase. + Enter it to proceed. + + .. note:: + + The signing a commit or pushing again with a signed push is not + recognized as a "change" by Gerrit, so if you forget to do either, you + need to change something about the commit to get Gerrit to accept the + patch again. Slightly tweaking the commit message is a good way. + + .. note:: + + This assumes you have git review set up and push.gpgsign + set to true. Otherwise: + + ``git push --signed gerrit HEAD:refs/for/master`` + + This assumes the gerrit remote is available, if not, configure + something like: ``ssh://ckd@git.opendaylight.org:29418/.git`` + where repo is something like docs or controller + +6. Verify the signature + + To do this, navigate to Gerrit and check for a green check next to your name in the patch. + + .. figure:: _static/gerrit-signed-push.png + + Example signed push to Gerrit. + Appendix ========