Gerrit Code Review - Uploading Changes

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:

Then copy the content of the public key file onto your clipboard, and paste it into Gerrit’s web interface:

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:

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:

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:

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.

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.:

To create new changes for review, simply push to the project’s magical refs/for/'branch' ref using any Git client tool:

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:

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.

Additional options may be specified when pushing 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.

If Change-Id lines are not available, then the user must use the manual mapping technique described below.

For more about Change-Ids, see Change-Id Lines.

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.

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:

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.

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:

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).

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:

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:

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:

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.

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.

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 mapping technique offered by using git push to a specific refs/changes/change# reference.

For more about Change-Ids, see Change-Id Lines.