| Gerrit Code Review - Uploading Changes | |
| ====================================== | |
| Gerrit supports three methods of uploading changes: | |
| * Use `repo upload`, to create changes for review | |
| * Use `git push`, to create changes for review | |
| * Use `git push`, and bypass code review | |
| All three methods rely on authentication, which must first be configured | |
| by the uploading user. | |
| Gerrit supports two methods of authenticating the uploading user. SSH | |
| public key, and HTTP/HTTPS. | |
| [[http]] | |
| HTTP/HTTPS | |
| ---------- | |
| On Gerrit installations that do not support SSH authentication, the | |
| user must authenticate via HTTP/HTTPS. | |
| When link:config-gerrit.html#auth.gitBasicAuth[gitBasicAuth] is enabled, | |
| the user is authenticated using standard BasicAuth and credentials validated | |
| using the same authentication method configured for the Gerrit Web UI. | |
| When gitBasicAuth is not configured, the user's HTTP credentials can be | |
| accessed within Gerrit by going to `Settings`, and then accessing the `HTTP | |
| Password` tab. | |
| For Gerrit installations where an link:config-gerrit.html#auth.httpPasswordUrl[HTTP password URL] | |
| is configured, the password can be obtained by clicking on `Obtain Password` | |
| and then following the site-specific instructions. On sites where this URL is | |
| not configured, the password can be obtained by clicking on `Generate Password`. | |
| SSH | |
| --- | |
| Each user uploading changes to Gerrit must configure one or more SSH | |
| public keys. The per-user SSH key list can be accessed over the web | |
| within Gerrit by `Settings`, and then accessing the `SSH Public Keys` | |
| tab. | |
| [[configure_ssh]] | |
| Configuration | |
| ~~~~~~~~~~~~~ | |
| To register a new SSH key for use with Gerrit, paste the contents of | |
| your `id_rsa.pub` or `id_dsa.pub` file into the text box and click | |
| the add button. Gerrit only understands SSH version 2 public keys. | |
| Keys may be supplied in either the OpenSSH format (key starts with | |
| `ssh-rsa` or `ssh-dss`) or the RFC 4716 format (file starts with | |
| `---- BEGIN SSH2 PUBLIC KEY ----`). | |
| Typically SSH keys are stored in your home directory, under `~/.ssh`. | |
| If you don't have any keys yet, you can create a new one and protect | |
| it with a passphrase: | |
| ==== | |
| ssh-keygen -t rsa | |
| ==== | |
| Then copy the content of the public key file onto your clipboard, | |
| and paste it into Gerrit's web interface: | |
| ==== | |
| cat ~/.ssh/id_rsa.pub | |
| ==== | |
| [TIP] | |
| Users who frequently upload changes will also want to consider | |
| starting an `ssh-agent`, and adding their private key to the list | |
| managed by the agent, to reduce the frequency of entering the | |
| key's passphrase. Consult `man ssh-agent`, or your SSH client's | |
| documentation, for more details on configuration of the agent | |
| process and how to add the private key. | |
| [[test_ssh]] | |
| Testing Connections | |
| ~~~~~~~~~~~~~~~~~~~ | |
| To verify your SSH key is working correctly, try using an SSH client | |
| to connect to Gerrit's SSHD port. By default Gerrit runs on | |
| port 29418, using the same hostname as the web server: | |
| ==== | |
| .................................................................. | |
| $ ssh -p 29418 sshusername@hostname | |
| **** Welcome to Gerrit Code Review **** | |
| Hi John Doe, you have successfully connected over SSH. | |
| Unfortunately, interactive shells are disabled. | |
| To clone a hosted Git repository, use: | |
| git clone ssh://sshusername@hostname:29418/REPOSITORY_NAME.git | |
| Connection to hostname closed. | |
| .................................................................. | |
| ==== | |
| In the command above, `sshusername` was configured as `Username` on | |
| the `Profile` tab of the `Settings` screen. If it is not set, | |
| propose a name and use `Select Username` to select the name. | |
| To determine the port number Gerrit is running on, visit the special | |
| information URL `http://'hostname'/ssh_info`, and copy the port | |
| number from the second field: | |
| ==== | |
| $ curl http://hostname/ssh_info | |
| hostname 29418 | |
| ==== | |
| If you are developing an automated tool to perform uploads to Gerrit, | |
| let the user supply the hostname or the web address for Gerrit, | |
| and obtain the port number on the fly from the `/ssh_info` URL. | |
| The returned output from this URL is always `'hostname' SP 'port'`, | |
| or `NOT_AVAILABLE` if the SSHD server is not currently running. | |
| git push | |
| -------- | |
| [[push_create]] | |
| Create Changes | |
| ~~~~~~~~~~~~~~ | |
| To create new changes for review, simply push to the project's | |
| magical `refs/for/'branch'` ref using any Git client tool: | |
| ==== | |
| git push ssh://sshusername@hostname:29418/projectname HEAD:refs/for/branch | |
| ==== | |
| E.g. `john.doe` can use git push to upload new changes for the | |
| `experimental` branch of project `kernel/common`, hosted at the | |
| `git.example.com` Gerrit server: | |
| ==== | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental | |
| ==== | |
| Each new commit uploaded by the `git push` client will be | |
| converted into a change record on the server. The remote ref | |
| `refs/for/experimental` is not actually created by Gerrit, even | |
| though the client's status messages may say otherwise. | |
| Other users (e.g. project owners) who have configured Gerrit to | |
| notify them of new changes will be automatically sent an email | |
| message when the push is completed. | |
| To include a short tag associated with all of the changes in the | |
| same group, such as the local topic branch name, append it after | |
| the destination branch name. In this example the short topic tag | |
| 'driver/i42' will be saved on each change this push creates or | |
| updates: | |
| ==== | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%topic=driver/i42 | |
| ==== | |
| If you are frequently uploading changes to the same Gerrit server, | |
| consider adding an SSH host block in `~/.ssh/config` to remember | |
| your username, hostname and port number. This permits the use of | |
| shorter URLs on the command line, such as: | |
| ==== | |
| $ cat ~/.ssh/config | |
| ... | |
| Host tr | |
| Hostname git.example.com | |
| Port 29418 | |
| User john.doe | |
| $ git push tr:kernel/common HEAD:refs/for/experimental | |
| ==== | |
| Specific reviewers can be requested and/or additional 'carbon | |
| copies' of the notification message may be sent by including these | |
| as options in the reference | |
| ==== | |
| git push tr:kernel/common HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com | |
| ==== | |
| The `r='email'` and `cc='email'` options may be specified as many | |
| times as necessary to cover all interested parties. Gerrit will | |
| automatically avoid sending duplicate email notifications, such as | |
| if one of the specified reviewers or CC addresses had also requested | |
| to receive all new change notifications. | |
| If you are frequently sending changes to the same parties and/or | |
| branches, consider adding a custom remote block to your project's | |
| `.git/config` file: | |
| ==== | |
| $ cat .git/config | |
| ... | |
| [remote "exp"] | |
| url = tr:kernel/common | |
| push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com | |
| $ git push exp | |
| ==== | |
| [[push_replace]] | |
| Replace Changes | |
| ~~~~~~~~~~~~~~~ | |
| To add an additional patch set to a change, ensure Change-Id | |
| lines were created in the original commit messages, and just use | |
| `git push URL HEAD:refs/for/...` as <<push_create,described above>>. | |
| Gerrit Code Review will automatically match the commits back to | |
| their original changes by taking advantage of the Change-Id lines. | |
| If Change-Id lines are not present in the commit messages, consider | |
| amending the message and copying the line from the change's page | |
| on the web, and then using `git push` as described above. | |
| If Change-Id lines are not available, then the user must use the | |
| manual mapping technique described below. | |
| For more about Change-Ids, see link:user-changeid.html[Change-Id Lines]. | |
| [[manual_replacement_mapping]] | |
| Manual Replacement Mapping | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| .Deprecation Warning | |
| **** | |
| The remainder of this section describes a manual method of replacing | |
| changes by matching each commit name to an existing change number. | |
| End-users should instead prefer to use Change-Id lines in their | |
| commit messages, as the process is then fully automated by Gerrit | |
| during normal uploads. | |
| See above for the preferred technique of replacing changes. | |
| **** | |
| To add an additional patch set to a change, replacing it with an | |
| updated version of the same logical modification, send the new | |
| commit to the change's ref. For example, to add the commit whose | |
| SHA-1 starts with `c0ffee` as a new patch set for change number | |
| `1979`, use the push refspec `c0ffee:refs/changes/1979` as below: | |
| ==== | |
| git push ssh://sshusername@hostname:29418/projectname c0ffee:refs/changes/1979 | |
| ==== | |
| This form can be combined together with `refs/for/'branchname'` | |
| (above) to simultaneously create new changes and replace changes | |
| during one network transaction. | |
| For example, consider the following sequence of events: | |
| ==== | |
| $ git commit -m A ; # create 3 commits | |
| $ git commit -m B | |
| $ git commit -m C | |
| $ git push ... HEAD:refs/for/master ; # upload for review | |
| ... A is 1500 ... | |
| ... B is 1501 ... | |
| ... C is 1502 ... | |
| $ git rebase -i HEAD~3 ; # edit "A", insert D before B | |
| ; # now series is A'-D-B'-C' | |
| $ git push ... | |
| HEAD:refs/for/master | |
| HEAD~3:refs/changes/1500 | |
| HEAD~1:refs/changes/1501 | |
| HEAD~0:refs/changes/1502 ; # upload replacements | |
| ==== | |
| At the final step during the push Gerrit will attach A' as a new | |
| patch set on change 1500; B' as a new patch set on change 1501; C' | |
| as a new patch set on 1502; and D will be created as a new change. | |
| Ensuring D is created as a new change requires passing the refspec | |
| `HEAD:refs/for/branchname`, otherwise Gerrit will ignore D and | |
| won't do anything with it. For this reason it is a good idea to | |
| always include the create change refspec when uploading replacements. | |
| [[bypass_review]] | |
| Bypass Review | |
| ~~~~~~~~~~~~~ | |
| Changes (and annotated tags) can be pushed directly into a | |
| repository, bypassing the review process. This is primarily useful | |
| for a project owner to create new branches, create annotated tags | |
| for releases, or to force-update a branch whose history needed to | |
| be rewritten. | |
| Gerrit restricts direct pushes that bypass review to: | |
| * `refs/heads/*`: any branch can be updated, created, deleted, | |
| or rewritten by the pusher. | |
| * `refs/tags/*`: annotated tag objects pointing to any other type | |
| of Git object can be created. | |
| To push branches, the proper access rights must be configured first. | |
| Here follows a few examples of how to configure this in Gerrit: | |
| * Update: Any existing branch can be fast-forwarded to a new commit. | |
| This is the safest mode as commits cannot be discarded. Creation | |
| of new branches is rejected. Can be configured with | |
| link:access-control.html#category_push_direct['Push'] access. | |
| * Create: Allows creation of a new branch if the name does not | |
| already designate an existing branch name. Needs | |
| link:access-control.html#category_create['Create Reference'] | |
| configured. Please note that once created, this permission doesn't | |
| grant the right to update the branch with further commits (see above | |
| for update details). | |
| * Delete: Implies Update, but also allows an existing | |
| branch to be deleted. Since a force push is effectively a delete | |
| followed by a create, but performed atomically on the server and | |
| logged, this also permits forced push updates to branches. | |
| To grant this access, configure | |
| link:access-control.html#category_push_direct['Push'] with the | |
| 'Force' option ticked. | |
| To push annotated tags, the `Push Annotated Tag` project right must | |
| be granted to one (or more) of the user's groups. There is only | |
| one level of access in this category. | |
| Project owners may wish to grant themselves `Push Annotated Tag` | |
| only at times when a new release is being prepared, and otherwise | |
| grant nothing at all. This ensures that accidental pushes don't | |
| make undesired changes to the public repository. | |
| [[auto_merge]] | |
| Auto-Merge during Push | |
| ~~~~~~~~~~~~~~~~~~~~~~ | |
| Changes can be directly submitted on push. This is primarily useful | |
| for teams that don't want to do code review but want to use Gerrit's | |
| submit strategies to handle contention on busy branches. Using | |
| `%submit` creates a change and submits it immediately, if the caller | |
| has link:access-control.html#category_submit[Submit] permission on | |
| `refs/for/<ref>` (e.g. on `refs/for/refs/heads/master`). | |
| ==== | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%submit | |
| ==== | |
| On auto-merge of a change neither labels nor submit rules are checked. | |
| If the merge fails the change stays open, but when pushing a new patch | |
| set the merge can be reattempted by using `%submit` again. | |
| [[base]] | |
| Selecting Merge Base | |
| ~~~~~~~~~~~~~~~~~~~~ | |
| By default new changes are opened only for new unique commits | |
| that have never before been seen by the Gerrit server. Clients | |
| may override that behavior and force new changes to be created | |
| by setting the merge base SHA-1 using the '%base' argument: | |
| ==== | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=$(git rev-parse origin/master) | |
| ==== | |
| repo upload | |
| ----------- | |
| repo is a multiple repository management tool, most commonly | |
| used by the Android Open Source Project. For more details, see | |
| link:http://source.android.com/source/using-repo.html[using repo]. | |
| [[repo_create]] | |
| Create Changes | |
| ~~~~~~~~~~~~~~ | |
| To upload changes to a project using `repo`, ensure the manifest's | |
| review field has been configured to point to the Gerrit server. | |
| Only the hostname or the web address needs to be given in the | |
| manifest file. During upload `repo` will automatically determine the | |
| correct port number by reading `http://'reviewhostname'/ssh_info` | |
| when its invoked. | |
| Each new commit uploaded by `repo upload` will be converted into | |
| a change record on the server. Other users (e.g. project owners) | |
| who have configured Gerrit to notify them of new changes will be | |
| automatically sent an email message. Additional notifications can | |
| be sent through command line options. | |
| For more details on using `repo upload`, see `repo help upload`. | |
| [[repo_replace]] | |
| Replace Changes | |
| ~~~~~~~~~~~~~~~ | |
| To replace changes, ensure Change-Id lines were created in the | |
| commit messages, and just use `repo upload`. | |
| Gerrit Code Review will automatically match the commits back to | |
| their original changes by taking advantage of their Change-Id lines. | |
| If Change-Id lines are not present in the commit messages, consider | |
| amending the message and copying the line from the change's page | |
| on the web. | |
| If Change-Id lines are not available, then the user must use the much | |
| more <<manual_replacement_mapping,manual mapping technique>> offered | |
| by using `git push` to a specific `refs/changes/change#` reference. | |
| For more about Change-Ids, see link:user-changeid.html[Change-Id Lines]. | |
| Gritty Details | |
| -------------- | |
| As Gerrit implements the entire SSH and Git server stack within its | |
| own process space, Gerrit maintains complete control over how the | |
| repository is updated, and what responses are sent to the `git push` | |
| client invoked by the end-user, or by `repo upload`. This allows | |
| Gerrit to provide magical refs, such as `refs/for/*` for new | |
| change submission and `refs/changes/*` for change replacement. | |
| When a push request is received to create a ref in one of these | |
| namespaces Gerrit performs its own logic to update the database, | |
| and then lies to the client about the result of the operation. | |
| A successful result causes the client to believe that Gerrit has | |
| created the ref, but in reality Gerrit hasn't created the ref at all. | |
| By implementing the entire server stack, Gerrit is also able to | |
| perform project level access control checks (to verify the end-user | |
| is permitted to access a project) prior to advertising the available | |
| refs, and potentially leaking information to a snooping client. | |
| Clients cannot tell the difference between 'project not found' and | |
| 'project exists, but access is denied'. | |
| Gerrit can also ensure users have completed a valid Contributor | |
| Agreement prior to accepting any transferred objects, and if an | |
| agreement is required, but not completed, it aborts the network | |
| connection before data is sent. This ensures that project owners | |
| can be certain any object available in their repository has been | |
| supplied under at least one valid agreement. | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] |