gerrit.wikimedia.org
Gerrit Code Review - Uploading Changes
Version V3.3.6
Table of Contents
HTTP/HTTPS
SSH
Public keys
Kerberos
Testing Connections
OpenSSH Host entry
git push
Create Changes
Push Options
Replace Changes
Bypass Review
Skip Validation
Auto-Merge during Push
Selecting Merge Base
Creating Changes for Merged Commits
repo upload
Create Changes
Replace Changes
Gritty Details
Gerrit supports three methods of uploading changes:
All three methods rely on authentication, which must first be configured by the uploading user.
Gerrit supports two protocols for uploading changes; SSH and HTTP/HTTPS. These may not all be available for you, depending on the server configuration.
HTTP/HTTPS
On Gerrit installations that do not support SSH authentication, the user must authenticate via HTTP/HTTPS.
The user is authenticated using standard BasicAuth. Depending on the value of auth.gitBasicAuthPolicy​, credentials are validated using:
When gitBasicAuthPolicy is set to LDAP or HTTP_LDAP and the user is authenticating with the LDAP username/password, the Git client config needs to have http.cookieFile set to a local file, otherwise every single call would trigger a full LDAP authentication and groups resolution which could introduce a noticeable latency on the overall execution and produce unwanted load to the LDAP server.
When gitBasicAuthPolicy is not LDAP, the user’s HTTP credentials can be regenerated by going to Settings, and then accessing the HTTP Password tab. Revocation can effectively be done by regenerating the password and then forgetting it.
For Gerrit installations where an 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
To upload changes over SSH, Gerrit supports two forms of authentication: a user’s public key or kerberos.
Unless your Gerrit instance is configured to support kerberos in your domain, only public key authentication can be used.
Public keys
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
TIPUsers 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.
Kerberos
A kerberos-enabled server configuration allows for zero configuration in an existing single-sign-on environment.
Your SSH client should be configured to enable kerberos authentication. For OpenSSH clients, this is controlled by the option GSSAPIAuthentication which should be set to yes.
Some Linux distributions have packaged OpenSSH to enable this by default (e.g. Debian, Ubuntu). If this is not the case for your distribution, enable it for Gerrit with this entry in your local SSH configuration:
Host gerrit.mydomain.tld GSSAPIAuthentication yes
Testing Connections
To verify your SSH authentication 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.
OpenSSH Host entry
If you are frequently uploading changes to the same Gerrit server, consider adding an SSH Host entry in your OpenSSH client configuration (~/.ssh/config) for that Gerrit server. It allows you use a single alias defining your username, hostname and port number whenever you’re accessing this Gerrit server in an SSH context (also command line SSH or SCP). Use this for easier to remember, shorter URLs, e.g.:
$ cat ~/.ssh/config ... Host mygerrit Hostname git.example.com Port 29418 User john.doe $ git clone mygerrit:myproject $ ssh mygerrit gerrit version $ scp -p mygerrit:hooks/commit-msg .git/hooks/
git push
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.
Push Options
Additional options may be specified when pushing changes.
Email Notifications
Uploaders can control to whom email notifications are sent by setting the notify option:
By default all email notifications are sent.
git push ssh://bot@git.example.com:29418/kernel/common HEAD:refs/for/master%notify=NONE
In addition uploaders can explicitly specify accounts that should be notified, regardless of the value that is given for the notify option. To notify a specific account specify it by an notify-to='email', notify-cc='email' or notify-bcc='email' option. These options can 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 accounts had also requested to receive all new change notifications. The accounts that are specified by notify-to='email', notify-cc='email' and notify-bcc='email' will only be notified about this one push. They are not added as reviewers or CCs, hence they are not automatically signed up to be notified on further updates of the change.
git push ssh://bot@git.example.com:29418/kernel/common HEAD:refs/for/master%notify=NONE,notify-to=a@a.com
Topic
To include a short topic associated with all of the changes in the same group, such as the local topic branch name, append it after the destination branch name or add it with the command line flag --push-option, aliased to -o. In this example the short topic name '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 // this is the same as: git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental -o topic=driver/i42
Hashtag
To include a hashtag associated with all of the changes in the same group, use the hashtag or t option:
// these are all equivalent git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%hashtag=stable-fix git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%t=stable-fix git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental -o hashtag=stable-fix git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental -o t=stable-fix
Private Changes
To push a private change or to turn a change private on push the private option can be specified:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%private
Omitting the private option when pushing updates to a private change doesn’t make change non-private again. To remove the private flag from a change on push, explicitly specify the remove-private option:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%remove-private
Work-In-Progress Changes
To push a wip change or to turn a change to wip the work-in-progress (or wip) option can be specified:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%wip
Omitting the wip option when pushing updates to a wip change doesn’t make change ready again. To remove the wip flag from a change on push, explicitly specify the ready option:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%ready
Only change owners, project owners and site administrators can specify work-in-progress and ready options on push.
The default for this option can be set as a user preference. If the preference is set so the default behavior is to create work-in-progress changes, this can be overridden with the ready option.
Patch Set Description
A patch set description can be applied by using the message (or m) option:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%m=This_is_a_rebase_on_master%21
NOTEgit push refs parameter does not allow spaces. Use the '_' or '+' character to represent spaces, and percent-encoding to represent other special chars. The above example will thus be applied as "This is a rebase on master!"
To avoid confusion in parsing the git ref, at least the following characters must be percent-encoded: " %^@.~-+_:/!". Note that some of the reserved characters (like tilde) are not escaped in the standard URL encoding rules, so a language-provided function (e.g. encodeURIComponent(), in javascript) might not suffice. To be safest, you might consider percent-encoding all non-alphanumeric characters (and all multibyte UTF-8 code points).
Publish Draft Comments
If you have draft comments on the change(s) that are updated by the push, the publish-comments option will cause them to be published:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%publish-comments
The default for this option can be set as a user preference. If the preference is set so the default behavior is to publish, this can be overridden with the no-publish-comments (or np) option.
Review Labels
Review labels can be applied to the change by using the label (or l) option in the reference:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%l=Verified+1
The l='label[score]' option may be specified more than once to apply multiple review labels.
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%l=Code-Review+1,l=Verified+1
The value is optional. If not specified, it defaults to +1 (if the label range allows it).
Change Edits
A change edit can be pushed by specifying the edit (or e) option on the reference:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%edit
There is at most one change edit per user and change. In order to push a change edit the change must already exist.
NOTEWhen a change edit already exists for a change then pushing with %edit replaces the existing change edit. This option is useful to rebase a change edit on the newest patch set when the rebase of the change edit in the web UI fails due to conflicts.
Reviewers
Specific reviewers can be requested and/or additional 'carbon copies' of the notification message may be sent by including the reviewer (or r) and cc options in the reference:
git push ssh://john.doe@git.example.com:29418/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 = ssh://john.doe@git.example.com:29418/kernel/common push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com $ git push exp
Trace
When pushing to Gerrit tracing can be enabled by setting the trace=<trace-id> push option. It is recommended to use the ID of the issue that is being investigated as trace ID.
git push -o trace=issue/123 ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master
It is also possible to omit the trace ID and get a unique trace ID generated.
Example Request
git push -o trace ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master
Enabling tracing results in additional logs with debug information that are written to the error_log. All logs that correspond to the traced request are associated with the trace ID. This trace ID is returned in the command output:
remote: TRACE_ID: 1534174322774-7edf2a7b
Given the trace ID an administrator can find the corresponding logs and investigate issues more easily.
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 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.
For more about Change-Ids, see Change-Id Lines.
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:
To push branches, the proper access rights must be configured first. Here follows a few examples of how to configure this in Gerrit:
To push annotated tags, the Create 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 Create 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.
Skip Validation
Even when a user has permission to push directly to a branch bypassing review, by default Gerrit will still validate any new commits, for example to check author/committer identities, and run validation plugins. This behavior can be bypassed with a push option:
git push -o skip-validation HEAD:master
Using the skip-validation option requires the user to have a specific set of permissions, in addition to those permissions already required to bypass review:
Plus these additional requirements on the project:
This option only applies when pushing directly to a branch bypassing review. Validation also occurs when pushing new changes for review, and that type of validation cannot be skipped.
The skip-validation option is always required when pushing more than a certain number of commits. This is the recommended approach when pushing lots of old history, since some validators would require rewriting history in order to make them pass.
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:
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.
This requires the caller to have Submit permission on refs/for/<ref> (e.g. on refs/for/refs/heads/master​). Note how this is different from the Submit permission on refs/heads/<ref>, and in particular you typically do not want to apply the Submit permission on refs/* (unless you are ok with bypassing submit rules).
Selecting Merge Base
By default new changes are opened only for new unique commits that are not part of any branch in refs/heads or the target branch. 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)
It is also possible to specify more than one '%base' argument. This may be useful when pushing a merge commit. Note that the '%' character has only to be provided once, for the first '%base' argument:
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=commit-id1,base=commit-id2
Creating Changes for Merged Commits
Normally, changes are only created for commits that have not yet been merged into the branch. In some cases, you may want to review a change that has already been merged. A new change for a merged commit can be created by using the '%merged' argument:
git push ssh://john.doe@git.example.com:29418/kernel/common my-merged-commit:refs/for/master%merged
This only creates one merged change at a time, corresponding to exactly my-merged-commit. It doesn’t walk all of history up to that point, which could be slow and create lots of unintended new changes. To create multiple new changes, run push multiple times.
repo upload
repo is a multiple repository management tool, most commonly used by the Android Open Source Project. For more details, see using repo.
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.
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.
For more about Change-Ids, see 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 review metadata, 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.
Part of Gerrit Code Review
Version v3.3.6