Code Review Server


This article has been moved from the old wiki.  The original may be found  here


This document describes how to use the code review service used by Linaro.

Where

* https://review.linaro.org/

Background

The code review instance is running gerrit.

This gerrit instance is meant for projects and teams that need a tool to perform code reviews.
It can be used also by all the other projects and teams in Linaro.

For more information on '''gerrit''', refer to the online user manual.

Who can use it

All Linaro employees, and all the people that have an account on Linaro Login.

Sign in

Authentication is handled by LDAP.  You will not need to register for an account, but you must sign into the gerrit instance at least once in order for your gerrit account to be created.

To sign in, click on the "Sign In" link in the upper right corner of the page, and enter your Linaro Login email address and Single-Sign-On password.

Once you are signed in, your name should appear in the upper right corner along with gear icon to change your account settings.

SSH Key

Public ssh keys from your Linaro Login account are synced automatically via LDAP every 10 minutes.  If you would like to add another key or if you need access before the next sync, you may add your public key manually.

Visit https://review.linaro.org/#/settings/ssh-keys (Or alternatively click on your name in top right corner -> Settings -> SSH Public Keys). If your public SSH user key there is not there, paste a copy of it into the "New SSH Key" text box and click on "Add Key".

Testing SSH

To test that ssh is working, run: 

ssh -p29418 $YOUR_GERRIT_USERNAME@review.linaro.org

Where `$YOUR_GERRIT_USERNAME` is the username you see once logged in on `review.linaro.org`.  If you are unsure of what your username is, you may find it by clicking on your name in the upper right corner  -> Settings and it will be listed as "User Name".

If you are able to connect successfully, you will see a login banner in response:

  ****    Welcome to Gerrit Code Review    ****

  Hi $YOUR_NAME, you have successfully connected over SSH.

  Unfortunately, interactive shells are disabled.
  To clone a hosted Git repository, use:

  git clone ssh://$YOUR_GERRIT_ID@review.linaro.org:29418/REPOSITORY_NAME.git

Pushing Changes for Review

git-review

The easiest way to push changes to gerrit is to use the git-review tool as it can hide some of the more tedious parts of submitting and managing reviews from the command line.  It can be installed as a python module by running:

pip install --user git-review	

This should create a command in your $PATH  for 'git-review'.

While some distributions do make the tool available through their native packaging systems, they might be using an older version which is relying upon obsoleted gerrit APIs.  Until such time as the distributions have caught up, you should ensure you're using at least version 1.28.0 or later by installing via 'pip'.

Once 'git-review' has been installed, it will be available as a git subcommand, and you can be access by running:

git review --help

If git-review has been successfully, it will include a git pre-hook that will create a new "ChangeId" for you upon commit for you.

If you do not already have a remote git branch named 'gerrit' setup, git-review will look for a file called '.gitreview' in the current directory and use the settings there.  Upon your first attempt to push to the gerrit remote, you will be prompted for the username to use, and git-review will perform the git push for you according to the parameters you specify.

git push

If you would prefer not use 'git-review to submit a change, the entire procedure for pushing a change manually is documented here.

It is suggested that you setup a remote 'gerrit' to use push your changes:

git remote add gerrit ssh://$YOUR_GERRIT_ID@review.linaro.org:29418/$REPOSITORY

And then submit your changes by pushing your local HEAD branch to the gerrit remote's "refs/for/master" branch:

git push gerrit HEAD:refs/for/master

The 'refs/for/*' branch in gerrit is a virtual branch.  It does not exist, and instead of creating it gerrit will instead create a 'refs/change/XYZ/A' branch and then generate a review against the real 'refs/heads/*' branch that corresponds with your 'refs/for/*' request.

For example:  The above push command specifying 'refs/for/master' will create a review against the contents of 'refs/heads/master'.  

Check the port!

Our review service is running on port 29418 and shares a server with our public git repository on the normal git protocol port of 9418.  If you attempt to push to ssh://$YOUR_GERRIT_ID@review.linaro.org/ authorization will be denied as your user will not be recognized.

Reviews may not be created through regular git!

It is possible you may have write access to the repository through the regular git interface on port 9418.  Do not try to push changes to 'refs/for/master' through the git interface as the request will not be intercepted by gerrit, no review will be created, and attempts to push to the 'refs/for/master' in gerrit will be blocked until the branch has been removed. 

Interacting with Gerrit

The primary method of using gerrit to make comments on projects or submit scores is through the web interface.  Documentation of the available features and a tour of the user interface is available in the online gerrit documentation.

You may also interact with gerrit over ssh using gerrit command line tools.

We do not currently support access to the gerrit REST API  through the public site.

* https://wiki.openstack.org/wiki/Gerrit_Workflow
* http://www.mediawiki.org/wiki/Gerrit/Tutorial
* http://www.mediawiki.org/wiki/Gerrit/Advanced_usage

Known Problems

* When you create a repository on the git instance, the project will not show up automatically on gerrit.
* The problem is with gerrit `project_list` cache. There is now a cron job that flush gerrit cache every hour. So, if you create a new project, you will have to wait at max 1 hour before it shows up in gerrit. If it is urgent, please talk with a gerrit admin or somebody from IT services.
* If your change involves copying or migrating files from one git repository into another, the gerrit review hook will complain about a lack of !ChangeId values in any commits prior to the migration. It is possible to add data to existing commits but if there are more than a couple, consider using a different mechanism to get the branch reviewed.
* If you run git-review -s after creating your branch, you need to add changeids to your commit messages. You can do this with interactive rebase, selecting 'reword' for each commit that needs a changeid. You probably shouldn't do this if you've published the patches.