To build a developer instance, you’ll need Bazel to compile the code, preferably launched with Bazelisk.

Git Setup

Getting the Source

Create a new client workspace:

  git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
  cd gerrit

The --recurse-submodules option is needed on git clone to ensure that the core plugins, which are included as git submodules, are also cloned.

Switching between branches

When using git checkout without --recurse-submodules to switch between branches, submodule revisions are not altered, which can result in:

  • Incorrect or unneeded plugin revisions.

  • Missing plugins.

After you switch branches, ensure that you have the correct versions of the submodules.

Caution
 If you store Eclipse or IntelliJ project files in the Gerrit source directories, do not run git clean -fdx. Doing so may remove untracked files and damage your project. For more information, see git-clean.

Run the following:

  git submodule update
  git clean -ffd

Compiling

For details, see Building with Bazel.

Testing

Running the acceptance tests

Gerrit contains acceptance tests that validate the Gerrit daemon via REST, SSH, and the Git protocol.

A new review site is created for each test and the Gerrit daemon is then started on that site. When the test is completed, the Gerrit daemon is shut down.

For instructions on running the acceptance tests with Bazel, see Running Unit Tests with Bazel.

End-to-end tests

This document describes how e2e (load or functional) test scenarios are implemented using Gatling.

Local server

Site Initialization

After you compile the project (above), run the Gerrit init command to create a test site:

  export GERRIT_SITE=~/gerrit_testsite
  $(bazel info output_base)/external/local_jdk/bin/java \
      -jar bazel-bin/gerrit.war init --batch --dev -d $GERRIT_SITE
Note
 You must use the same Java version that Bazel used for the build, which is available at $(bazel info output_base)/external/local_jdk/bin/java.

This command takes two parameters:

  • --batch assigns default values to several Gerrit configuration options. To learn more about these options, see Configuration.

  • --dev configures the Gerrit server to use the authentication option, DEVELOPMENT_BECOME_ANY_ACCOUNT, which enables you to switch between different users to explore how Gerrit works. To learn more about setting up Gerrit for development, see Gerrit Code Review: Developer Setup.

After initializing the test site, Gerrit starts serving in the background. A web browser displays the Start page.

On the Start page, you can:

  1. Log in as the account you created during the initialization process.

  2. Register additional accounts.

  3. Create projects.

To shut down the daemon, run:

  $GERRIT_SITE/bin/gerrit.sh stop

Working with the Local Server

To create more accounts on your development instance:

  1. Click 'become' in the upper right corner.

  2. Select 'Switch User'.

  3. Register a new account.

  4. Configure your SSH key.

Use the ssh protocol to clone from and push to the local server. For example, to clone a repository that you’ve created through the admin interface, run:

git clone ssh://username@localhost:29418/projectname

To use the HTTP protocol, run:

git clone http://username@localhost:8080/projectname

The default password for user admin is secret. You can regenerate a password in the UI under User Settings — HTTP credentials. The password can be stored locally to avoid retyping it:

git config --global credential.helper store
git pull

To create changes as users of Gerrit would, run:

git push origin HEAD:refs/for/master

Running the Daemon

The daemon can be launched directly from the build area, without copying to the test site:

  $(bazel info output_base)/external/local_jdk/bin/java \
     -jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE \
     --console-log
Note
 To learn why using java -jar isn’t sufficient, see this explanation.

To debug the Gerrit server of this test site:

  1. Open a debug port (such as port 5005). To do so, insert the following code immediately after -jar in the previous command. To learn how to attach IntelliJ, see Debugging a remote Gerrit server.

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

Running the Daemon with Gerrit Inspector

Gerrit Inspector is an interactive scriptable environment you can use to inspect and modify the internal state of the system.

Gerrit Inspector appears on the system console whenever the system starts. Leaving the Inspector shuts down the Gerrit instance.

To troubleshoot, the Inspector enables interactive work as well as running of Python scripts.

To start the Inspector, add the '-s' option to the daemon start command:

  $(bazel info output_base)/external/local_jdk/bin/java \
     -jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE -s
Note
 To learn why using java -jar isn’t sufficient, see this explanation.

Inspector examines Java libraries, loads the initialization scripts, and starts a command line prompt on the console:

  Welcome to the Gerrit Inspector
  Enter help() to see the above again, EOF to quit and stop Gerrit
  Jython 2.5.2 (Release_2_5_2:7206, Mar 2 2011, 23:12:06)
  [OpenJDK 64-Bit Server VM (Sun Microsystems Inc.)] on java1.6.0 running for
  Gerrit 2.3-rc0-163-g01967ef
  >>>

When the Inspector is enabled, you can use Gerrit as usual and all interfaces (including HTTP and SSH) are available.

Caution
 When using the Inspector, be careful not to modify the internal state of the system.

Setup for backend developers

Configuring Eclipse

To use the Eclipse IDE for development, see Eclipse Setup.

To configure the Eclipse workspace with Bazel, see Eclipse integration with Bazel.

Configuring IntelliJ IDEA

See IntelliJ Setup for details.

Setup for frontend developers

See Frontend Developer Setup.

Part of Gerrit Code Review