blob: cbb152c374793be8be6ac87a0a173fbc01aa04ab [file] [log] [blame]
Shawn O. Pearcee31d02c2009-12-08 12:21:37 -08001Gerrit Code Review - Uploading Changes
2======================================
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -08003
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -07004Gerrit supports three methods of uploading changes:
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -08005
6* Use `repo upload`, to create changes for review
7* Use `git push`, to create changes for review
8* Use `git push`, and bypass code review
9
David Pursehousebaac4252013-01-25 17:42:19 +090010All three methods rely on authentication, which must first be configured
11by the uploading user.
12
13Gerrit supports two methods of authenticating the uploading user. SSH
14public key, and HTTP/HTTPS.
15
Edwin Kempin60ab8532013-03-27 14:33:46 +010016[[http]]
David Pursehousebaac4252013-01-25 17:42:19 +090017HTTP/HTTPS
18----------
19
20On Gerrit installations that do not support SSH authentication, the
21user must authenticate via HTTP/HTTPS.
22
23When link:config-gerrit.html#auth.gitBasicAuth[gitBasicAuth] is enabled,
24the user is authenticated using standard BasicAuth and credentials validated
25using the same authentication method configured for the Gerrit Web UI.
26
27When gitBasicAuth is not configured, the user's HTTP credentials can be
28accessed within Gerrit by going to `Settings`, and then accessing the `HTTP
29Password` tab.
30
31For Gerrit installations where an link:config-gerrit.html#auth.httpPasswordUrl[HTTP password URL]
32is configured, the password can be obtained by clicking on `Obtain Password`
33and then following the site-specific instructions. On sites where this URL is
34not configured, the password can be obtained by clicking on `Generate Password`.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080035
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070036SSH
37---
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080038
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070039Each user uploading changes to Gerrit must configure one or more SSH
40public keys. The per-user SSH key list can be accessed over the web
Edwin Kempinb5df3b82011-10-10 11:31:14 +020041within Gerrit by `Settings`, and then accessing the `SSH Public Keys`
42tab.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080043
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070044[[configure_ssh]]
45Configuration
46~~~~~~~~~~~~~
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080047
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070048To register a new SSH key for use with Gerrit, paste the contents of
49your `id_rsa.pub` or `id_dsa.pub` file into the text box and click
50the add button. Gerrit only understands SSH version 2 public keys.
51Keys may be supplied in either the OpenSSH format (key starts with
52`ssh-rsa` or `ssh-dss`) or the RFC 4716 format (file starts with
53`---- BEGIN SSH2 PUBLIC KEY ----`).
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080054
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070055Typically SSH keys are stored in your home directory, under `~/.ssh`.
56If you don't have any keys yet, you can create a new one and protect
57it with a passphrase:
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080058
59====
60 ssh-keygen -t rsa
61====
62
63Then copy the content of the public key file onto your clipboard,
64and paste it into Gerrit's web interface:
65
66====
67 cat ~/.ssh/id_rsa.pub
68====
69
70[TIP]
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070071Users who frequently upload changes will also want to consider
David Pursehouse221d4f62012-06-08 17:38:08 +090072starting an `ssh-agent`, and adding their private key to the list
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070073managed by the agent, to reduce the frequency of entering the
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080074key's passphrase. Consult `man ssh-agent`, or your SSH client's
75documentation, for more details on configuration of the agent
76process and how to add the private key.
77
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -070078[[test_ssh]]
79Testing Connections
80~~~~~~~~~~~~~~~~~~~
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080081
82To verify your SSH key is working correctly, try using an SSH client
David Pursehouse221d4f62012-06-08 17:38:08 +090083to connect to Gerrit's SSHD port. By default Gerrit runs on
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080084port 29418, using the same hostname as the web server:
85
86====
Edwin Kempinfb95a1b2011-10-05 10:08:00 +020087..................................................................
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080088 $ ssh -p 29418 sshusername@hostname
Edwin Kempinfb95a1b2011-10-05 10:08:00 +020089
90 **** Welcome to Gerrit Code Review ****
91
92 Hi John Doe, you have successfully connected over SSH.
93
94 Unfortunately, interactive shells are disabled.
95 To clone a hosted Git repository, use:
96
97 git clone ssh://sshusername@hostname:29418/REPOSITORY_NAME.git
98
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -080099 Connection to hostname closed.
Edwin Kempinfb95a1b2011-10-05 10:08:00 +0200100..................................................................
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800101====
102
Edwin Kempinfb95a1b2011-10-05 10:08:00 +0200103In the command above, `sshusername` was configured as `Username` on
104the `Profile` tab of the `Settings` screen. If it is not set,
105propose a name and use `Select Username` to select the name.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800106
107To determine the port number Gerrit is running on, visit the special
108information URL `http://'hostname'/ssh_info`, and copy the port
109number from the second field:
110
111====
112 $ curl http://hostname/ssh_info
113 hostname 29418
114====
115
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800116If you are developing an automated tool to perform uploads to Gerrit,
117let the user supply the hostname or the web address for Gerrit,
118and obtain the port number on the fly from the `/ssh_info` URL.
119The returned output from this URL is always `'hostname' SP 'port'`,
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700120or `NOT_AVAILABLE` if the SSHD server is not currently running.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800121
122
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700123git push
124--------
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800125
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700126[[push_create]]
127Create Changes
128~~~~~~~~~~~~~~
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800129
David Pursehouse221d4f62012-06-08 17:38:08 +0900130To create new changes for review, simply push to the project's
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800131magical `refs/for/'branch'` ref using any Git client tool:
132
133====
Shawn Pearce69928a62013-02-24 18:01:27 -0800134 git push ssh://sshusername@hostname:29418/projectname HEAD:refs/for/branch
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800135====
136
137E.g. `john.doe` can use git push to upload new changes for the
138`experimental` branch of project `kernel/common`, hosted at the
139`git.example.com` Gerrit server:
140
141====
142 git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental
143====
144
145Each new commit uploaded by the `git push` client will be
146converted into a change record on the server. The remote ref
147`refs/for/experimental` is not actually created by Gerrit, even
148though the client's status messages may say otherwise.
149
150Other users (e.g. project owners) who have configured Gerrit to
151notify them of new changes will be automatically sent an email
152message when the push is completed.
153
Shawn O. Pearced50c94e2010-07-15 12:24:11 -0700154To include a short tag associated with all of the changes in the
155same group, such as the local topic branch name, append it after
Shawn Pearce69928a62013-02-24 18:01:27 -0800156the destination branch name. In this example the short topic tag
Shawn O. Pearced50c94e2010-07-15 12:24:11 -0700157'driver/i42' will be saved on each change this push creates or
158updates:
159
160====
Shawn Pearce69928a62013-02-24 18:01:27 -0800161 git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%topic=driver/i42
Shawn O. Pearced50c94e2010-07-15 12:24:11 -0700162====
163
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800164If you are frequently uploading changes to the same Gerrit server,
165consider adding an SSH host block in `~/.ssh/config` to remember
166your username, hostname and port number. This permits the use of
167shorter URLs on the command line, such as:
168
169====
170 $ cat ~/.ssh/config
171 ...
172 Host tr
173 Hostname git.example.com
174 Port 29418
175 User john.doe
176
177 $ git push tr:kernel/common HEAD:refs/for/experimental
178====
179
Edwin Kempinb5df3b82011-10-10 11:31:14 +0200180Specific reviewers can be requested and/or additional 'carbon
181copies' of the notification message may be sent by including these
Shawn Pearce69928a62013-02-24 18:01:27 -0800182as options in the reference
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800183
184====
Shawn Pearce69928a62013-02-24 18:01:27 -0800185 git push tr:kernel/common HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800186====
187
Shawn Pearce69928a62013-02-24 18:01:27 -0800188The `r='email'` and `cc='email'` options may be specified as many
189times as necessary to cover all interested parties. Gerrit will
190automatically avoid sending duplicate email notifications, such as
191if one of the specified reviewers or CC addresses had also requested
192to receive all new change notifications.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800193
194If you are frequently sending changes to the same parties and/or
195branches, consider adding a custom remote block to your project's
196`.git/config` file:
197
198====
199 $ cat .git/config
200 ...
Shawn Pearce69928a62013-02-24 18:01:27 -0800201 [remote "exp"]
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800202 url = tr:kernel/common
Shawn Pearce69928a62013-02-24 18:01:27 -0800203 push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800204
Shawn Pearce69928a62013-02-24 18:01:27 -0800205 $ git push exp
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800206====
207
208
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700209[[push_replace]]
210Replace Changes
211~~~~~~~~~~~~~~~
212
213To add an additional patch set to a change, ensure Change-Id
214lines were created in the original commit messages, and just use
215`git push URL HEAD:refs/for/...` as <<push_create,described above>>.
216Gerrit Code Review will automatically match the commits back to
217their original changes by taking advantage of the Change-Id lines.
218
219If Change-Id lines are not present in the commit messages, consider
220amending the message and copying the line from the change's page
221on the web, and then using `git push` as described above.
222
223If Change-Id lines are not available, then the user must use the
224manual mapping technique described below.
225
226For more about Change-Ids, see link:user-changeid.html[Change-Id Lines].
227
Edwin Kempin930187e2011-01-27 10:13:42 +0100228[[manual_replacement_mapping]]
Edwin Kempinb2e42c82011-01-13 09:29:57 +0100229Manual Replacement Mapping
230^^^^^^^^^^^^^^^^^^^^^^^^^^
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700231
232.Deprecation Warning
233****
234The remainder of this section describes a manual method of replacing
235changes by matching each commit name to an existing change number.
236End-users should instead prefer to use Change-Id lines in their
237commit messages, as the process is then fully automated by Gerrit
238during normal uploads.
239
240See above for the preferred technique of replacing changes.
241****
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800242
243To add an additional patch set to a change, replacing it with an
244updated version of the same logical modification, send the new
245commit to the change's ref. For example, to add the commit whose
246SHA-1 starts with `c0ffee` as a new patch set for change number
247`1979`, use the push refspec `c0ffee:refs/changes/1979` as below:
248
249====
250 git push ssh://sshusername@hostname:29418/projectname c0ffee:refs/changes/1979
251====
252
253This form can be combined together with `refs/for/'branchname'`
254(above) to simultaneously create new changes and replace changes
255during one network transaction.
256
257For example, consider the following sequence of events:
258
259====
260 $ git commit -m A ; # create 3 commits
261 $ git commit -m B
262 $ git commit -m C
263
264 $ git push ... HEAD:refs/for/master ; # upload for review
265 ... A is 1500 ...
266 ... B is 1501 ...
267 ... C is 1502 ...
268
269 $ git rebase -i HEAD~3 ; # edit "A", insert D before B
270 ; # now series is A'-D-B'-C'
Shawn O. Pearced6078462009-11-02 10:37:01 -0800271 $ git push ...
272 HEAD:refs/for/master
273 HEAD~3:refs/changes/1500
274 HEAD~1:refs/changes/1501
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800275 HEAD~0:refs/changes/1502 ; # upload replacements
276====
277
278At the final step during the push Gerrit will attach A' as a new
279patch set on change 1500; B' as a new patch set on change 1501; C'
280as a new patch set on 1502; and D will be created as a new change.
281
282Ensuring D is created as a new change requires passing the refspec
283`HEAD:refs/for/branchname`, otherwise Gerrit will ignore D and
284won't do anything with it. For this reason it is a good idea to
285always include the create change refspec when uploading replacements.
286
287
Edwin Kempin913eab12011-05-06 08:18:24 +0200288[[bypass_review]]
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700289Bypass Review
290~~~~~~~~~~~~~
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800291
292Changes (and annotated tags) can be pushed directly into a
293repository, bypassing the review process. This is primarily useful
294for a project owner to create new branches, create annotated tags
295for releases, or to force-update a branch whose history needed to
296be rewritten.
297
298Gerrit restricts direct pushes that bypass review to:
299
300* `refs/heads/*`: any branch can be updated, created, deleted,
301or rewritten by the pusher.
302* `refs/tags/*`: annotated tag objects pointing to any other type
Nico Sallembien950e4152010-03-16 15:45:33 -0700303of Git object can be created.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800304
Fredrik Luthanderc10f9e72012-01-23 17:00:45 +0100305To push branches, the proper access rights must be configured first.
306Here follows a few examples of how to configure this in Gerrit:
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800307
308* Update: Any existing branch can be fast-forwarded to a new commit.
309This is the safest mode as commits cannot be discarded. Creation
Fredrik Luthanderc10f9e72012-01-23 17:00:45 +0100310of new branches is rejected. Can be configured with
311link:access-control.html#category_push_direct['Push'] access.
312* Create: Allows creation of a new branch if the name does not
313already designate an existing branch name. Needs
314link:access-control.html#category_create['Create Reference']
315configured. Please note that once created, this permission doesn't
316grant the right to update the branch with further commits (see above
317for update details).
318* Delete: Implies Update, but also allows an existing
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800319branch to be deleted. Since a force push is effectively a delete
320followed by a create, but performed atomically on the server and
321logged, this also permits forced push updates to branches.
Fredrik Luthanderc10f9e72012-01-23 17:00:45 +0100322To grant this access, configure
323link:access-control.html#category_push_direct['Push'] with the
324'Force' option ticked.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800325
326To push annotated tags, the `Push Annotated Tag` project right must
327be granted to one (or more) of the user's groups. There is only
328one level of access in this category.
329
330Project owners may wish to grant themselves `Push Annotated Tag`
331only at times when a new release is being prepared, and otherwise
332grant nothing at all. This ensures that accidental pushes don't
333make undesired changes to the public repository.
334
335
Edwin Kempinbfa06212013-04-04 16:06:39 +0200336[[auto_merge]]
337Auto-Merge during Push
338~~~~~~~~~~~~~~~~~~~~~~
339
340Changes can be directly submitted on push. This is primarily useful
341for teams that don't want to do code review but want to use Gerrit's
342submit strategies to handle contention on busy branches. Using
343`%submit` creates a change and submits it immediately, if the caller
344has link:access-control.html#category_submit[Submit] permission on
345`refs/for/<ref>` (e.g. on `refs/for/refs/heads/master`).
346
347====
348 git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%submit
349====
350
351On auto-merge of a change neither labels nor submit rules are checked.
352If the merge fails the change stays open, but when pushing a new patch
353set the merge can be reattempted by using `%submit` again.
354
355
Shawn Pearce5d8a2902013-04-22 11:50:23 -0700356[[base]]
357Selecting Merge Base
358~~~~~~~~~~~~~~~~~~~~
359
360By default new changes are opened only for new unique commits
361that have never before been seen by the Gerrit server. Clients
362may override that behavior and force new changes to be created
363by setting the merge base SHA-1 using the '%base' argument:
364
365====
366 git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=$(git rev-parse origin/master)
367====
368
369
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700370repo upload
371-----------
372
373repo is a multiple repository management tool, most commonly
374used by the Android Open Source Project. For more details, see
Orgad Shanehc9e11de2012-12-24 16:49:09 +0200375link:http://source.android.com/source/using-repo.html[using repo].
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700376
377[[repo_create]]
378Create Changes
379~~~~~~~~~~~~~~
380
381To upload changes to a project using `repo`, ensure the manifest's
382review field has been configured to point to the Gerrit server.
383Only the hostname or the web address needs to be given in the
384manifest file. During upload `repo` will automatically determine the
385correct port number by reading `http://'reviewhostname'/ssh_info`
386when its invoked.
387
388Each new commit uploaded by `repo upload` will be converted into
389a change record on the server. Other users (e.g. project owners)
390who have configured Gerrit to notify them of new changes will be
391automatically sent an email message. Additional notifications can
392be sent through command line options.
393
394For more details on using `repo upload`, see `repo help upload`.
395
396[[repo_replace]]
397Replace Changes
398~~~~~~~~~~~~~~~
399
400To replace changes, ensure Change-Id lines were created in the
Cecilia Svenssoncd2491d2012-01-20 14:22:30 +0100401commit messages, and just use `repo upload`.
402Gerrit Code Review will automatically match the commits back to
403their original changes by taking advantage of their Change-Id lines.
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700404
405If Change-Id lines are not present in the commit messages, consider
406amending the message and copying the line from the change's page
407on the web.
408
409If Change-Id lines are not available, then the user must use the much
Cecilia Svenssoncd2491d2012-01-20 14:22:30 +0100410more <<manual_replacement_mapping,manual mapping technique>> offered
411by using `git push` to a specific `refs/changes/change#` reference.
Shawn O. Pearce518fe3f2009-08-22 15:40:58 -0700412
413For more about Change-Ids, see link:user-changeid.html[Change-Id Lines].
414
415
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800416Gritty Details
417--------------
418
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800419As Gerrit implements the entire SSH and Git server stack within its
420own process space, Gerrit maintains complete control over how the
421repository is updated, and what responses are sent to the `git push`
422client invoked by the end-user, or by `repo upload`. This allows
Edwin Kempincdb0e002011-09-08 14:23:30 +0200423Gerrit to provide magical refs, such as `refs/for/*` for new
424change submission and `refs/changes/*` for change replacement.
Shawn O. Pearcee61a3c62009-01-29 08:42:41 -0800425When a push request is received to create a ref in one of these
426namespaces Gerrit performs its own logic to update the database,
427and then lies to the client about the result of the operation.
428A successful result causes the client to believe that Gerrit has
429created the ref, but in reality Gerrit hasn't created the ref at all.
430
431By implementing the entire server stack, Gerrit is also able to
432perform project level access control checks (to verify the end-user
433is permitted to access a project) prior to advertising the available
434refs, and potentially leaking information to a snooping client.
435Clients cannot tell the difference between 'project not found' and
436'project exists, but access is denied'.
437
438Gerrit can also ensure users have completed a valid Contributor
439Agreement prior to accepting any transferred objects, and if an
440agreement is required, but not completed, it aborts the network
441connection before data is sent. This ensures that project owners
442can be certain any object available in their repository has been
443supplied under at least one valid agreement.
Shawn O. Pearce5500e692009-05-28 15:55:01 -0700444
445GERRIT
446------
447Part of link:index.html[Gerrit Code Review]