Gerrit supports three methods of uploading changes:
repo upload, to create changes for review
git push, to create changes for review
git push, and bypass code review
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.
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:
The randomly generated HTTP password on the
HTTP Passwordtab in the user settings page if
The LDAP password if
Both, the HTTP and the LDAP passwords (in this order) if
When gitBasicAuthPolicy is not
LDAP, the user’s HTTP credentials can
be regenerated by going to
Settings, and then accessing the
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
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.
To register a new SSH key for use with Gerrit, paste the contents of
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-dss) or the RFC 4716 format (file starts with
---- BEGIN SSH2
PUBLIC KEY ----).
Typically SSH keys are stored in your home directory, under
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:
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.
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
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
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
Select Username to select the name.
To determine the port number Gerrit is running on, visit the special
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/
To create new changes for review, simply push to the project’s magical
refs/for/'branch' ref using any Git client
git push ssh://sshusername@hostname:29418/projectname HEAD:refs/for/branch
john.doe can use git push to upload new changes for the
experimental branch of project
kernel/common, hosted at the
git push ssh://firstname.lastname@example.org: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
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.
Uploaders can control to whom email notifications are sent by setting
NONE: No email notification will be sent to anyone.
OWNER: Only the change owner is notified.
OWNER_REVIEWERS: Only owners and reviewers will be notified. This includes all reviewers, existing reviewers of the change and new reviewers that are added by the
revieweroption or by mentioning in the commit message.
ALL: All email notifications will be sent. This includes notifications to watchers, users that have starred the change, CCs and the committer and author of the uploaded commit.
By default all email notifications are sent.
git push ssh://email@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
To notify a specific account specify it by an
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
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
git push ssh://firstname.lastname@example.org:29418/kernel/common HEAD:refs/for/master%notify=NONE,email@example.com
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 or add it with the command line flag
--push-option, aliased to
-o. In this example the short topic tag
driver/i42 will be saved on each change this push creates or
git push ssh://firstname.lastname@example.org:29418/kernel/common HEAD:refs/for/experimental%topic=driver/i42 // this is the same as: git push ssh://email@example.com:29418/kernel/common HEAD:refs/for/experimental -o topic=driver/i42
To push a private change or to turn a change private on push the
private option can be
git push ssh://firstname.lastname@example.org:29418/kernel/common HEAD:refs/for/master%private
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
git push ssh://email@example.com:29418/kernel/common HEAD:refs/for/master%remove-private
To push a wip change or to turn a change to wip the
wip) option can be
git push ssh://firstname.lastname@example.org:29418/kernel/common HEAD:refs/for/master%wip
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
git push ssh://email@example.com:29418/kernel/common HEAD:refs/for/master%ready
A comment message can be applied to the change by using the
git push ssh://firstname.lastname@example.org:29418/kernel/common HEAD:refs/for/experimental%m=This_is_a_rebase_on_master
git push refs parameter does not allow spaces. Use the _ character instead, it will then be applied as “This is a rebase on master”.
Publish Draft Comments
If you have draft comments on the change(s) that are updated by the
publish-comments option will cause them to be
git push ssh://email@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
Review labels can be applied to the change by using the
option in the
git push ssh://firstname.lastname@example.org:29418/kernel/common HEAD:refs/for/experimental%l=Verified+1
l='label[score]' option may be specified more than once to apply
git push ssh://email@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).
A change edit can be pushed by specifying the
e) option on
git push ssh://firstname.lastname@example.org: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.
When a change edit already exists for a change then pushing with
%editreplaces 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.
Specific reviewers can be requested and/or additional carbon copies of
the notification message may be sent by including the
cc options in the
git push ssh://email@example.com:29418/kernel/common HEAD:firstname.lastname@example.org,email@example.com
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
$ cat .git/config ... [remote "exp"] url = ssh://firstname.lastname@example.org:29418/kernel/common push = HEAD:email@example.com,firstname.lastname@example.org $ git push exp
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.
Manual Replacement Mapping
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
git push ssh://sshusername@hostname:29418/projectname c0ffee:refs/changes/1979
This form can be combined together with
to simultaneously create new changes and replace changes during one
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.
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 Push access.
Create: Allows creation of a new branch if the name does not already designate an existing branch name. Needs 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 Push with the Force option ticked.
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:
git push -o skip-validation HEAD:master
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:
Project must not require Signed-off-by.
Project must not have
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.
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
creates a change and submits it
git push ssh://email@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
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 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://firstname.lastname@example.org: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://email@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://firstname.lastname@example.org: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 is a multiple repository management tool, most commonly used by the Android Open Source Project. For more details, see using repo.
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.
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
git push to a specific
For more about Change-Ids, see Change-Id Lines.
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.
Part of Gerrit Code Review