Gerrit Code Review: Installation, Configuration & Usage

Recently I had to build a new development team within a large company. As part of it, had to implement best practices and processes for the development team. The challenge was to find tools, frameworks, and processes that are critical to the productivity and agility of the team as well as to work with the existing infrastructure, frameworks and tools within the organization. During the course of this, I had to select a code review tool and evaluated a number of them:

1. Crucible
2. Review Board
3. Phabricator
4. Gerrit

Each of one has their own merits and pitfalls. Here I will explain a quick setup and configuration of Gerrit as I had to go through a number of sites and documentation to figure out how to get this done. Gerrit would like to be the owner of your Git repository. If this can be implemented, everything will work great. But in our case, we have a centrally hosted Git repository and all the checkins should be available in this central repo. The solution to this problem is to setup Gerrit Replication. This is not a great idea. If people are directly pushing to the master repository, AND Gerrit is pushing, this will mess up the code base. The solution is to have one-way pull and push to different repositories as described below:

Here are the steps involved in getting this work.

Install Gerrit

Install the server with all the defaults

java -jar gerrit.war init -d ~/gerrit-server

Setup User

By default, Gerrit will be installed with OpenID. Login into Gerrit UI using any authentication (e.g. Google). The first user to login will be added to the Administrator group.

1. Create SSH Keys
2. Login to Gerrit UI and copy the key generated in the previous step (e.g. id_rsa.pub) into your Account Setup
3. Setup a username to connect to Git Server hosted by the Gerrit (e.g. gerrit-user)
4. Test connectivity from your local client to Gerrit Server

   ssh gerrit-user@gerrit-server -p 29418
   

   This will give a nice welcome message and inform that interactive shells are disabled

Import and existing project

To import an existing project, create a new project in Gerrit Server and then run import.

1. Create a new project called gerrit-test

   ssh -p 29418 gerrit-user@gerrit-server gerrit create-project --name gerrit-test
   

2. Create access to gerrit-user to newly created project gerrit-test
   1. Log into Gerrit UI and create a new user group called gerrit-test-group
   2. Go to Projects->List->gerrit-test->Access
   3. Grant access to refs/* for Create Reference permission to user group gerrit-test-group
3. Import project

   cd dev/gerrit-test
   push ssh://gerrit-user@gerrit-server:29418/gerrit-test *:*
   

Setup local Git Repo for Gerrit

Install Gerrit hooks

cd dev/gerrit-test
scp -p -P 29418 gerrit-user@gerrit-server:hooks/commit-msg .git/hooks

Setup Gerrit server replication to push changes to central repository

1. Setup the local ssh keys to connect to the Git server
2. Setup the key for git host

   git-server> ssh-keygen -t rsa git-host >> ~/.ssh/known_hosts
   

3. Add a new file called replication.config in the gerrit/etc directory with the following contents

   [remote "central-git-repo"]
     url = git@git-host:/{name}.git
   

4. Shutdown and restart the Gerrit Server

Test

1. Make some changes in to a local file
2. Commit the changes
3. Push the changes to Gerrit

   git push ssh://gerrit-user@gerrit-server:29418/gerrit-test HEAD:refs/for/master
   

4. Login to Gerrit UI
5. Approve the changes with +2
6. Gerrit will push the changes to the master git repository. Verify the latest changes are indeed replicated by Gerrit Server