docs/gerrit.rst

   1 ############
   2 Gerrit Guide
   3 ############
   4
   5 How to push to Gerrit
   6 =====================
   7
   8 It is highly recommended to use ssh to push to Gerrit to push code to Gerrit.
   9 In the event that you cannot use ssh such as corporate firewall blocking you
  10 then falling back to pushing via https should work.
  11
  12 Using ssh to push to Gerrit
  13 ---------------------------
  14
  15 # TODO
  16
  17 Using https to push to Gerrit
  18 -----------------------------
  19
  20 Gerrit does not allow you to use your regular account credentials when pushing
  21 via https. Instead it requires you to first generate a http password via the
  22 Web U and use that as the password when pushing via https.
  23
  24 .. figure:: images/gerrit-https-password-setup.png
  25
  26    Setting up an https password to push using https instead of ssh.
  27
  28 To do this:
  29
  30 1. navigate to https://git.opendaylight.org/gerrit/#/settings/http-password
  31    (Steps 1, 2 and 3 in the image above.)
  32 2. click the **Generate Password** button.
  33
  34 Gerrit will then generate a random password which you will need to use as your
  35 password when using git to push code to Gerrit via https.
  36
  37 Signing Gerrit Commits
  38 ======================
  39
  40 1. Generate your GPG key.
  41
  42    The following instructions work on a Mac, but the general approach
  43    should be the same on other OSes.
  44
  45    .. code-block:: bash
  46
  47       brew install gpg2  # If you don't have homebrew, get that here: http://brew.sh/
  48       gpg2 --gen-key
  49       # pick 1 for "RSA and RSA"
  50       # enter 4096 to creat a 4096-bit key
  51       # enter an expiration time, I picked 2y for 2 years
  52       # enter y to accept the expiration time
  53       # pick O or Q to accept your name/email/comment
  54       # enter a pass phrase twice. it seems like backspace doesn't work, so type carefully
  55       gpg2 --fingerprint
  56       # you'll get something like this:
  57       # spectre:~ ckd$ gpg2 --fingerprint
  58       # /Users/ckd/.gnupg/pubring.gpg
  59       # -----------------------------
  60       # pub   4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
  61       #       Key fingerprint = 7C37 02AC D651 1FA7 9209  48D3 5DD5 0C4B F566 C9B1
  62       # uid       [ultimate] Colin Dixon <colin at colindixon.com>
  63       # sub   4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
  64       # you're looking for the part after 4096R, which is your key ID
  65       gpg2 --send-keys $KEY_ID
  66       # in the above example, the $KEY_ID would be F566C9B1
  67       # you should see output like this:
  68       # gpg: sending key F566C9B1 to hkp server keys.gnupg.net
  69
  70    If you're trying to participate in an OpenDaylight keysigning, then
  71    send the output of ``gpg2 --fingerprint $KEY_ID`` to
  72    keysigning@opendaylight.org
  73
  74    .. code-block:: bash
  75
  76       gpg2 --fingerprint $KEY_ID
  77       # in the above example, the $KEY_ID would be F566C9B1
  78       # in my case, the output was:
  79       # pub   4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
  80       #       Key fingerprint = 7C37 02AC D651 1FA7 9209  48D3 5DD5 0C4B F566 C9B1
  81       # uid       [ultimate] Colin Dixon <colin at colindixon.com>
  82       # sub   4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
  83
  84 2. Install gpg, instead of or addition to gpg2. It appears as though
  85    gpg2 has annoying things that it does when asking for your
  86    passphrase, which I haven't debugged yet.
  87
  88    .. note:: you can tell git to use gpg by doing:
  89      ``git config --global gpg.program gpg2``
  90      but that then will seem to struggle asking for your
  91      passphrase unless you have your gpg-agent set up right.
  92
  93 3. Add you GPG to Gerrit
  94
  95    a. Run the following at the CLI:
  96
  97       .. code-block:: bash
  98
  99          gpg --export -a $FINGER_PRINT
 100          # e.g., gpg --export -a F566C9B1
 101          # in my case the output looked like:
 102          # -----BEGIN PGP PUBLIC KEY BLOCK-----
 103          # Version: GnuPG v2
 104          #
 105          # mQINBFUisGABEAC/DkcjNUhxQkRLdfbfdlq9NlfDusWri0cXLVz4YN1cTUTF5HiW
 106          # ...
 107          # gJT+FwDvCGgaE+JGlmXgjv0WSd4f9cNXkgYqfb6mpji0F3TF2HXXiVPqbwJ1V3I2
 108          # NA+l+/koCW0aMReK
 109          # =A/ql
 110          # -----END PGP PUBLIC KEY BLOCK-----
 111
 112    b. Browse to https://git.opendaylight.org/gerrit/#/settings/gpg-keys
 113    c. Click Add Key...
 114    d. Copy the output from the above command, paste it into the box,
 115       and click Add
 116
 117 4. Set up your git to sign commits and push signatures
 118
 119    .. code-block:: bash
 120
 121       git config commit.gpgsign true
 122       git config push.gpgsign true
 123       git config user.signingkey $FINGER_PRINT
 124       # e.g., git config user.signingkey F566C9B1
 125
 126    .. note:: you can do this instead with ``git commit -S``
 127       You can use ``git commit -S`` and ``git push --signed``
 128       on the CLI instead of configuring it in config if you
 129       want to control which commits use your signature.
 130
 131 5. Commit and push a change
 132
 133    a. change a file
 134    b. ``git commit -asm "test commit"``
 135
 136       .. note:: this should result in git asking you for your passphrase
 137
 138    c. ``git review``
 139
 140       .. note:: this should result in git asking you for your passphrase
 141
 142       .. note:: annoyingly, the presence of a gpgp signature or pushing
 143         of a gpg signature isn't recognized as a "change" by
 144         Gerrit, so if you forget to do either, you need to change
 145         something about the commit to get Gerrit to accept the
 146         patch again. Slightly tweaking the commit message is a
 147         good way.
 148
 149       .. note:: this assumes you have git review set up and push.gpgsign
 150         set to true. Otherwise:
 151
 152         ``git push --signed gerrit HEAD:refs/for/master``
 153
 154         .. note:: this assumes you have your gerrit remote set up, if
 155             not it's something like:
 156             ``ssh://ckd@git.opendaylight.org:29418/<repo>.git``
 157             where repo is something like docs or controller
 158
 159 6. Verify that your commit is signed by going to the change in Gerrit
 160    and checking for a green check (instead of a blue ?) next to your
 161    name.
 162
 163
 164 Setting up gpg-agent on a Mac
 165 -----------------------------
 166
 167 #. Install ``gpg-agent`` and ``pinentry-mac`` using ``brew``::
 168
 169       brew install gpg-agent pinentry-mac
 170
 171 #. Edit your ``~/.gnupg/gpg.conf`` contain the line::
 172
 173       use-agent
 174
 175 #. Edit your ``~/.gnupg/gpg-agent.conf`` to something like::
 176
 177       use-standard-socket
 178       enable-ssh-support
 179       default-cache-ttl 600
 180       max-cache-ttl 7200
 181       pinentry-program /usr/local/bin/pinentry-mac
 182
 183 #. Edit your ``.bash_profile`` or equivalent file to contain the
 184    following:
 185
 186    .. code-block:: bash
 187
 188       [ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info
 189       if [ -S "${GPG_AGENT_INFO%%:*}" ]; then
 190         export GPG_AGENT_INFO
 191       else
 192         eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info )
 193       fi
 194
 195 #. Kill any stray ``gpg-agent`` daemons running::
 196
 197       sudo killall gpg-agent
 198
 199 #. Restart your terminal (or log in and out) to reload the your
 200    ``.bash_profile`` or equivalent file
 201
 202 #. The next time a git operation makes a call to gpg, it should use
 203    your gpg-agent to run a GUI window to ask for your passphrase and
 204    give you an option to save your passphrase in the keychain.
 205
 206    .. figure:: images/pinentry-mac.png