[Tutorial] How-to installation and configuration Gerrit v2.10 with GitHub oAuth

This tutorial is useful?

  • Awesome

    Votes: 13 72.2%
  • Yes

    Votes: 5 27.8%
  • No

    Votes: 0 0.0%

  • Total voters
    18
Search This thread

codexc

Senior Member
Jan 30, 2010
3,059
8,102
Beirut
www.probam.net
This tutorial explains the installation and configuration of the Gerrit code review system .

What is Gerrit?
Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. The user interface of Gerrit is based on
Google Web Toolkit and its Git implementation is based on JGit.
A contributor can use Gerrit to suggest a code change. Other developers can review the code change and suggest improvements. If a Gerrit change request needs improvement, it is possible to update it with a new set of changes. Once the suggested changes are accepted by the reviewers, they can be applied via Gerrit to the underlying Git repository.
Gerrit makes code reviews easier by showing changes in a side-by-side display. It also allows the reviewer to add comments to every single line changed.Development takes place at the Gerrit project hosted by Google Code.


Gerrit v2.10 online documentation:
You find detailed information about Gerrit at: Gerrit Code Review - A Quick Introduction.

  1. Installation of Gerrit
    Packages Requirements
  2. Initialize the Site
    Create Directory
    Download Gerrit
    Install Gerrit
    Setup the database and user
  3. Troubleshooting
    Plugins
    GitHub authentication
    Gravatar Provider Plugin
    Delete Project Plugin
  4. Themes
  5. TIPS


Installation of Gerrit

Packages Requirements:

Install Java 1.7
Code:
sudo apt-get install openjdk-7-jre
Select Default Java Version

Code:
sudo update-alternatives --config java
Code:
There are 3 choices for the alternative java (providing /usr/bin/java).
  Selection    Path                                     Priority   Status
------------------------------------------------------------
  0            /usr/lib/jvm/java-6-oracle/jre/bin/java   67        auto mode
  1            /usr/lib/jvm/java-6-oracle/jre/bin/java   67        manual mode
  2            /usr/lib/jvm/java-6-sun/jre/bin/java      63        manual mode
* 3            /usr/lib/jvm/java-7-oracle/jre/bin/java   66        manual mode
Code:
java -version
  java version "1.7.0_21"
  ...

Install Gitweb
Code:
sudo apt-get install gitweb


Initialize the Site

1. Create Directory
you can create the directory wherever you want but i will use global path

Code:
mkdir ~/gerrit/
Code:
cd ~/gerrit/

2. Download Gerrit

Download the latest Gerrit release from Gerrit download page. The download is a
Code:
.war
file which you can directly add to your servlet container.

Code:
wget https://gerrit-releases.storage.googleapis.com/gerrit-2.10-rc0.war

3. Install Gerrit

Setup the database and user
Code:
CREATE USER 'gerrit'@'localhost' IDENTIFIED BY 'yourpassword';
CREATE DATABASE reviewdb;
GRANT ALL ON reviewdb.* TO 'gerrit'@'localhost';
FLUSH PRIVILEGES;
exit;


It’s time to run the initialization

Code:
java -jar gerrit*.war init

you can also set subfolder
Code:
java -jar gerrit*.war init -d ~/gerrit/subfolder


Table 1. Gerrit setup options

Location of Git repositories
Location of Git repositories, default is the
Code:
git
directory in the installation folder of your Gerrit installation.


Database server type
Gerrit supports several databases, by default it uses a preconfigured H2 database, but we will use mysql

Listen on port
Allows you to configure the port Gerrit is listening to, Gerrit by default listens on port 29418 for SSH access and on port 8080 for web access. This can be changed if the ports are already used.

Authentication method
The easiest way of configuring access to Gerrit is to use Github instead of OpenID Single Sign-on


Processing 2. Gerrit setup options

Code:
Setting up gerrit (2.10-rc0) ...
Starting Gerrit Code Review : gerrit
No Gerrit site found. Will Initialize Gerrit first...

*** Gerrit Code Review 2.10
***
Create '/root/gerrit/review_site' [Y/n]?

*** Git Repositories
***
Location of Git repositories   [git]:

*** SQL Database
***
Database server type           [H2/?]: mysql

Gerrit Code Review is not shipped with MySQL Connector/J 5.1.10
**  This library is required for your configuration. **
Download and install it now [Y/n]?
Downloading http://repo2.maven.org/maven2/mysql/mysql-connector-java/5.1.10/mysql-connector-java-5.1.10.jar ... OK
Checksum mysql-connector-java-5.1.10.jar OK
Server hostname                [localhost]:
Server port                    [(MYSQL default)]:
Database name                  [reviewdb]:
Database username              [gerrit2]: gerrit
gerrit2's password             : yourpassword
confirm password : yourpassword

*** User Authentication
***
Authentication method          [OPENID/?]: http
Get username from custom HTTP header [y/N]? y
SSO logout URL                 :

*** Email Delivery
***
SMTP server hostname           [localhost]: smtp.gmail.com
SMTP server port               [(default)]: 587
SMTP encryption                [NONE/?]: TLS
SMTP username                  : [email protected]
SMTP password                  : you_password

*** Container Process
***
Run as                         [gerrit]:
Java runtime                   [/usr/lib/jvm/java-7-oracle/jre]: /usr/lib/jvm/java-7-oracle/jre

Copy gerrit.war to /root/gerrit/bin/gerrit.war [Y/n]? Y
Copying gerrit.war to /root/gerrit/bin/gerrit.war

*** SSH Daemon
***
Listen on address              [*]:
Listen on port                 [29418]:

Gerrit Code Review is not shipped with Bouncy Castle Crypto v144
  If available, Gerrit can take advantage of features
  in the library, but will also function without it.
Download and install it now [Y/n]?
Downloading http://www.bouncycastle.org/download/bcprov-jdk16-144.jar ... OK
Checksum bcprov-jdk16-144.jar OK
Generating SSH host key ... rsa... dsa... done

*** HTTP Daemon
***
Behind reverse proxy           [y/N]? y
Proxy uses SSL (https://)      [y/N]? n
Listen on address              [*]:
Listen on port                 [8081]:
Canonical URL                  [http://review.probam.net/]: https://your-domain.com/
Gerrit can be launched manually:
Code:
~/gerrit/bin/gerrit.sh start


Troubleshooting:

some time you will facing some issues and you got FAILD when trying to start Gerrit
"gc.startTime" is not configured
Code:
INFO  com.google.gerrit.server.config.ScheduleConfig : gc schedule parameter "gc.startTime" is not configured
Section gc allows to configure the git garbage collection and schedules it to run periodically. It will be triggered and executed sequentially for all projects. more info

Examples:

Code:
[gc]
  startTime=Fri 12:00
  interval =2 day
Error opening database "Sleep interrupted" [8000-173] :

Code:
com.google.gerrit.server.cache.h2.H2CacheFactory : Enabling disk cache /.../cache
to get rid of this error , run
Code:
java -jar gerrit*.war reindex


Plugins :


built-in plugins you can setup during installation
  • commit-message-length-validator v2.10-rc0
  • download-commands v2.10-rc0
  • replication v2.10-rc0
  • reviewnotes v2.10-rc0
  • singleusergroup v2.10-rc0

Additional Plugins (pre-compiled) we going to install them

GitHub authentication

The Gerrit GitHub plugin can be found under the Gerrit plugins/github repository on https://gerrit-review.googlesource.com/#/admin/projects/plugins/github. It is open source under the Apache 2.0 license and can be cloned and built using the Java 6 JDK or higher and Maven.

Download (github-oauth*.jar, the GitHub OAuth library for authenticating Gerrit users)
Install the GitHub OAuth filter into the Gerrit libraries (/lib under the Gerrit site directory)

The GitHub OAuth JAR file needs to copied to the Gerrit /lib directory; this is required to allow Gerrit to use it for filtering all HTTP requests and enforcing the GitHub three-step authentication process:

Download (github-plugin*.jar, the Gerrit plugin for integrating with GitHub repositories and pull requests)
Install the GitHub Plugin into the Gerrit plugins (/plugins under the Gerrit site directory)

The GitHub plugin includes the additional support for the overall configuration, the advanced GitHub repositories replication, and the integration of pull requests into the Code Review process.

Register Gerrit as a GitHub OAuth application

Before going through the Gerrit init, we need to tell GitHub to trust Gerrit as a partner application. This is done through the generation of a ClientId/ClientSecret pair associated to the exact Gerrit URLs that will be used for initiating the 3-step OAuth authentication.

We can register a new application in GitHub through the URL https://github.com/settings/applications/new, where the following three fields are requested:

  • Application name : It is the logical name of the application authorized to access GitHub, for example, Gerrit.
  • Main URL : The Gerrit canonical web URL used for redirecting to GitHub OAuth authentication, for example, https://myhost.mydomain:port.
  • Callback URL : The URL that GitHub should redirect to when the OAuth authentication is successfully completed, for example, https://myhost.mydomain:port/#/.

Running Gerrit init to configure GitHub OAuth

Code:
$ ~/gerrit/bin/gerrit.sh stop 
Stopping Gerrit Code Review: OK 
$ cd /opt/gerrit 
$ java -jar gerrit.war init  
[...] 
*** User Authentication
***
Authentication method          []: 
HTTP RETURN
Get username from custom HTTP header [Y/n]? 
Y RETURN
Username HTTP header           []: 
GITHUB_USER RETURN
SSO logout URL                 : 
/oauth/reset RETURN
*** GitHub Integration
***
GitHub URL                     [https://github.com]: 
RETURN
Use GitHub for Gerrit login ?  [Y/n]? 
Y RETURN
ClientId                       []: 
384cbe2e8d98192f9799 RETURN
ClientSecret                   []: 
f82c3f9b3802666f2adcc4 RETURN
Initialized ~/gerrit

Restart Gerrit
Code:
~/gerrit/bin/gerrit.sh restart

Using GitHub login and anonymous read support for Gerrit

Gerrit is now fully configured to register and authenticate users through GitHub OAuth. When opening the browser to access any Gerrit web pages, we are automatically redirected to the GitHub for login.

The best part in this tutorial you will able to open Gerrit pages for anonymous users !!
(put in etc/gerrit.config)

Code:
[auth]
    type=HTTP
    httpHeader=GITHUB_USER
    httpDisplayNameHeader=GITHUB_NAME
    httpEmailHeader=GITHUB_EMAIL
    loginUrl=/login
    loginText=GitHub Sign-in
    registerPageUrl=/plugins/github-plugin/static/account.html
    gitBasicAuth=true


Check Installed Plugins :

Code:
ssh <user>@<host> -p29418 gerrit plugin ls

Install Gravatar Provider Plugin:

Code:
ssh <user>@<host> -p29418 gerrit plugin install -n gravatar.jar \ 
http://ci.gerritforge.com/view/Plugins-master/job/Plugin_gravatar_master/lastSuccessfulBuild/artifact/gravatar.jar

Install Delete Project Plugin:
Code:
ssh <user>@<host> -p29418 gerrit plugin install -n delete-project.jar \ 
http://ci.gerritforge.com/view/Plugins-master/job/Plugin_delete-project_master/lastSuccessfulBuild/artifact/delete-project.jar


Themes :

Code:
[theme]
    backgroundColor=FCFEEF
    textColor=000000
    trimColor=D4E9A9
    selectionColor=FFFFCC
    topMenuColor=D4E9A9
    changeTableOutdatedColor=F08080
[theme "signed-in]
    backgroundColor=FFFFFF

TIPS:
if you are using gerrit on remote server and you need to work with Gerrit remotely , you can enable allowRemoteAdmin

Code:
[plugins]
    allowRemoteAdmin=true;

Sources and References in this Tutorial :


Regards,
Hany alsamman
 
Last edited:

atrohde

Senior Member
Oct 26, 2010
84
12
Milwaukee
Could you explain in the step: Running Gerrit init to configure GitHub OAuth
what did you do exactly ?
why did you cd to /opt/gerrit ?

I'm wondering the same thing. gerrit doesn't exist under "opt". when running "gerrit.war" from bin it doesn't give any settings for github, just all the initial setup settings again.

I've got it setup to the point it gives me the error "Check the HTTP server's authentication settings." I created httpd.conf to show what the error page says and included it in my apache2.conf. Not sure where to go from here.

Edit: An update "2.11-rc0" has been posted. I did a fresh install with launchpad's openid which works great now.
 
Last edited:

Top Liked Posts

  • There are no posts matching your filters.
  • 19
    This tutorial explains the installation and configuration of the Gerrit code review system .

    What is Gerrit?
    Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. The user interface of Gerrit is based on
    Google Web Toolkit and its Git implementation is based on JGit.
    A contributor can use Gerrit to suggest a code change. Other developers can review the code change and suggest improvements. If a Gerrit change request needs improvement, it is possible to update it with a new set of changes. Once the suggested changes are accepted by the reviewers, they can be applied via Gerrit to the underlying Git repository.
    Gerrit makes code reviews easier by showing changes in a side-by-side display. It also allows the reviewer to add comments to every single line changed.Development takes place at the Gerrit project hosted by Google Code.


    Gerrit v2.10 online documentation:
    You find detailed information about Gerrit at: Gerrit Code Review - A Quick Introduction.

    1. Installation of Gerrit
      Packages Requirements
    2. Initialize the Site
      Create Directory
      Download Gerrit
      Install Gerrit
      Setup the database and user
    3. Troubleshooting
      Plugins
      GitHub authentication
      Gravatar Provider Plugin
      Delete Project Plugin
    4. Themes
    5. TIPS


    Installation of Gerrit

    Packages Requirements:

    Install Java 1.7
    Code:
    sudo apt-get install openjdk-7-jre
    Select Default Java Version

    Code:
    sudo update-alternatives --config java
    Code:
    There are 3 choices for the alternative java (providing /usr/bin/java).
      Selection    Path                                     Priority   Status
    ------------------------------------------------------------
      0            /usr/lib/jvm/java-6-oracle/jre/bin/java   67        auto mode
      1            /usr/lib/jvm/java-6-oracle/jre/bin/java   67        manual mode
      2            /usr/lib/jvm/java-6-sun/jre/bin/java      63        manual mode
    * 3            /usr/lib/jvm/java-7-oracle/jre/bin/java   66        manual mode
    Code:
    java -version
      java version "1.7.0_21"
      ...

    Install Gitweb
    Code:
    sudo apt-get install gitweb


    Initialize the Site

    1. Create Directory
    you can create the directory wherever you want but i will use global path

    Code:
    mkdir ~/gerrit/
    Code:
    cd ~/gerrit/

    2. Download Gerrit

    Download the latest Gerrit release from Gerrit download page. The download is a
    Code:
    .war
    file which you can directly add to your servlet container.

    Code:
    wget https://gerrit-releases.storage.googleapis.com/gerrit-2.10-rc0.war

    3. Install Gerrit

    Setup the database and user
    Code:
    CREATE USER 'gerrit'@'localhost' IDENTIFIED BY 'yourpassword';
    CREATE DATABASE reviewdb;
    GRANT ALL ON reviewdb.* TO 'gerrit'@'localhost';
    FLUSH PRIVILEGES;
    exit;


    It’s time to run the initialization

    Code:
    java -jar gerrit*.war init

    you can also set subfolder
    Code:
    java -jar gerrit*.war init -d ~/gerrit/subfolder


    Table 1. Gerrit setup options

    Location of Git repositories
    Location of Git repositories, default is the
    Code:
    git
    directory in the installation folder of your Gerrit installation.


    Database server type
    Gerrit supports several databases, by default it uses a preconfigured H2 database, but we will use mysql

    Listen on port
    Allows you to configure the port Gerrit is listening to, Gerrit by default listens on port 29418 for SSH access and on port 8080 for web access. This can be changed if the ports are already used.

    Authentication method
    The easiest way of configuring access to Gerrit is to use Github instead of OpenID Single Sign-on


    Processing 2. Gerrit setup options

    Code:
    Setting up gerrit (2.10-rc0) ...
    Starting Gerrit Code Review : gerrit
    No Gerrit site found. Will Initialize Gerrit first...
    
    *** Gerrit Code Review 2.10
    ***
    Create '/root/gerrit/review_site' [Y/n]?
    
    *** Git Repositories
    ***
    Location of Git repositories   [git]:
    
    *** SQL Database
    ***
    Database server type           [H2/?]: mysql
    
    Gerrit Code Review is not shipped with MySQL Connector/J 5.1.10
    **  This library is required for your configuration. **
    Download and install it now [Y/n]?
    Downloading http://repo2.maven.org/maven2/mysql/mysql-connector-java/5.1.10/mysql-connector-java-5.1.10.jar ... OK
    Checksum mysql-connector-java-5.1.10.jar OK
    Server hostname                [localhost]:
    Server port                    [(MYSQL default)]:
    Database name                  [reviewdb]:
    Database username              [gerrit2]: gerrit
    gerrit2's password             : yourpassword
    confirm password : yourpassword
    
    *** User Authentication
    ***
    Authentication method          [OPENID/?]: http
    Get username from custom HTTP header [y/N]? y
    SSO logout URL                 :
    
    *** Email Delivery
    ***
    SMTP server hostname           [localhost]: smtp.gmail.com
    SMTP server port               [(default)]: 587
    SMTP encryption                [NONE/?]: TLS
    SMTP username                  : [email protected]
    SMTP password                  : you_password
    
    *** Container Process
    ***
    Run as                         [gerrit]:
    Java runtime                   [/usr/lib/jvm/java-7-oracle/jre]: /usr/lib/jvm/java-7-oracle/jre
    
    Copy gerrit.war to /root/gerrit/bin/gerrit.war [Y/n]? Y
    Copying gerrit.war to /root/gerrit/bin/gerrit.war
    
    *** SSH Daemon
    ***
    Listen on address              [*]:
    Listen on port                 [29418]:
    
    Gerrit Code Review is not shipped with Bouncy Castle Crypto v144
      If available, Gerrit can take advantage of features
      in the library, but will also function without it.
    Download and install it now [Y/n]?
    Downloading http://www.bouncycastle.org/download/bcprov-jdk16-144.jar ... OK
    Checksum bcprov-jdk16-144.jar OK
    Generating SSH host key ... rsa... dsa... done
    
    *** HTTP Daemon
    ***
    Behind reverse proxy           [y/N]? y
    Proxy uses SSL (https://)      [y/N]? n
    Listen on address              [*]:
    Listen on port                 [8081]:
    Canonical URL                  [http://review.probam.net/]: https://your-domain.com/
    Gerrit can be launched manually:
    Code:
    ~/gerrit/bin/gerrit.sh start


    Troubleshooting:

    some time you will facing some issues and you got FAILD when trying to start Gerrit
    "gc.startTime" is not configured
    Code:
    INFO  com.google.gerrit.server.config.ScheduleConfig : gc schedule parameter "gc.startTime" is not configured
    Section gc allows to configure the git garbage collection and schedules it to run periodically. It will be triggered and executed sequentially for all projects. more info

    Examples:

    Code:
    [gc]
      startTime=Fri 12:00
      interval =2 day
    Error opening database "Sleep interrupted" [8000-173] :

    Code:
    com.google.gerrit.server.cache.h2.H2CacheFactory : Enabling disk cache /.../cache
    to get rid of this error , run
    Code:
    java -jar gerrit*.war reindex


    Plugins :


    built-in plugins you can setup during installation
    • commit-message-length-validator v2.10-rc0
    • download-commands v2.10-rc0
    • replication v2.10-rc0
    • reviewnotes v2.10-rc0
    • singleusergroup v2.10-rc0

    Additional Plugins (pre-compiled) we going to install them

    GitHub authentication

    The Gerrit GitHub plugin can be found under the Gerrit plugins/github repository on https://gerrit-review.googlesource.com/#/admin/projects/plugins/github. It is open source under the Apache 2.0 license and can be cloned and built using the Java 6 JDK or higher and Maven.

    Download (github-oauth*.jar, the GitHub OAuth library for authenticating Gerrit users)
    Install the GitHub OAuth filter into the Gerrit libraries (/lib under the Gerrit site directory)

    The GitHub OAuth JAR file needs to copied to the Gerrit /lib directory; this is required to allow Gerrit to use it for filtering all HTTP requests and enforcing the GitHub three-step authentication process:

    Download (github-plugin*.jar, the Gerrit plugin for integrating with GitHub repositories and pull requests)
    Install the GitHub Plugin into the Gerrit plugins (/plugins under the Gerrit site directory)

    The GitHub plugin includes the additional support for the overall configuration, the advanced GitHub repositories replication, and the integration of pull requests into the Code Review process.

    Register Gerrit as a GitHub OAuth application

    Before going through the Gerrit init, we need to tell GitHub to trust Gerrit as a partner application. This is done through the generation of a ClientId/ClientSecret pair associated to the exact Gerrit URLs that will be used for initiating the 3-step OAuth authentication.

    We can register a new application in GitHub through the URL https://github.com/settings/applications/new, where the following three fields are requested:

    • Application name : It is the logical name of the application authorized to access GitHub, for example, Gerrit.
    • Main URL : The Gerrit canonical web URL used for redirecting to GitHub OAuth authentication, for example, https://myhost.mydomain:port.
    • Callback URL : The URL that GitHub should redirect to when the OAuth authentication is successfully completed, for example, https://myhost.mydomain:port/#/.

    Running Gerrit init to configure GitHub OAuth

    Code:
    $ ~/gerrit/bin/gerrit.sh stop 
    Stopping Gerrit Code Review: OK 
    $ cd /opt/gerrit 
    $ java -jar gerrit.war init  
    [...] 
    *** User Authentication
    ***
    Authentication method          []: 
    HTTP RETURN
    Get username from custom HTTP header [Y/n]? 
    Y RETURN
    Username HTTP header           []: 
    GITHUB_USER RETURN
    SSO logout URL                 : 
    /oauth/reset RETURN
    *** GitHub Integration
    ***
    GitHub URL                     [https://github.com]: 
    RETURN
    Use GitHub for Gerrit login ?  [Y/n]? 
    Y RETURN
    ClientId                       []: 
    384cbe2e8d98192f9799 RETURN
    ClientSecret                   []: 
    f82c3f9b3802666f2adcc4 RETURN
    Initialized ~/gerrit

    Restart Gerrit
    Code:
    ~/gerrit/bin/gerrit.sh restart

    Using GitHub login and anonymous read support for Gerrit

    Gerrit is now fully configured to register and authenticate users through GitHub OAuth. When opening the browser to access any Gerrit web pages, we are automatically redirected to the GitHub for login.

    The best part in this tutorial you will able to open Gerrit pages for anonymous users !!
    (put in etc/gerrit.config)

    Code:
    [auth]
        type=HTTP
        httpHeader=GITHUB_USER
        httpDisplayNameHeader=GITHUB_NAME
        httpEmailHeader=GITHUB_EMAIL
        loginUrl=/login
        loginText=GitHub Sign-in
        registerPageUrl=/plugins/github-plugin/static/account.html
        gitBasicAuth=true


    Check Installed Plugins :

    Code:
    ssh <user>@<host> -p29418 gerrit plugin ls

    Install Gravatar Provider Plugin:

    Code:
    ssh <user>@<host> -p29418 gerrit plugin install -n gravatar.jar \ 
    http://ci.gerritforge.com/view/Plugins-master/job/Plugin_gravatar_master/lastSuccessfulBuild/artifact/gravatar.jar

    Install Delete Project Plugin:
    Code:
    ssh <user>@<host> -p29418 gerrit plugin install -n delete-project.jar \ 
    http://ci.gerritforge.com/view/Plugins-master/job/Plugin_delete-project_master/lastSuccessfulBuild/artifact/delete-project.jar


    Themes :

    Code:
    [theme]
        backgroundColor=FCFEEF
        textColor=000000
        trimColor=D4E9A9
        selectionColor=FFFFCC
        topMenuColor=D4E9A9
        changeTableOutdatedColor=F08080
    [theme "signed-in]
        backgroundColor=FFFFFF

    TIPS:
    if you are using gerrit on remote server and you need to work with Gerrit remotely , you can enable allowRemoteAdmin

    Code:
    [plugins]
        allowRemoteAdmin=true;

    Sources and References in this Tutorial :


    Regards,
    Hany alsamman
    4
    @banguru @DerRomtester @Eyenseo @jakew02 @KNIGHT97
    @LabBoy97 @supreethms @tire_007 @williamfold @Xado

    Thanks for read this tutorial !, don't hesitate to ask if there any good question :good:
Our Apps
Get our official app!
The best way to access XDA on your phone
Nav Gestures
Add swipe gestures to any Android
One Handed Mode
Eases uses one hand with your phone