Updated git submodules
[docs.git] / 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