From Wikitech
Jump to navigation Jump to search

Become an Administrator

Gerrit management is granted by the Administrators group which includes the gerrit2 system user and the LDAP group gerritadmin. To gain Administrator right, one thus has to be added in LDAP.

Being an administrator grants all global capabilities as described at Gerrit Access Control - global capabilities. It is essentially the same as having root access on Gerrit.

The LDAP groups membership is cached in Gerrit for 1 hour (as of January 2020). One thus has to wait for the cache to expire or have an administrator to flush the cache:

   ssh -p 29418 gerrit flush-caches --cache ldap_groups

If right is given as a one off, one would most probably want to be removed from the group once the rights are no more required.

Creating new repositories

See mw:Git/Creating new repositories. Those without administrative access to Gerrit should use mw:Gerrit/New repositories instead.

Inspecting an account settings

Since Gerrit 2.15, accounts are stored in All-Users.git. One first need to find the account reference, that can be done by checking which references a user can read on All-Users.git:

$ ssh -p 29418 gerrit ls-user-refs --project All-Users --user '' 

Note: for accounts having extended permissions on All-Users.git, that will show all references which is not useful.

Then on the server side (or remotely if you have privileges), you can list the configuration files and dump their content:

$ cd /srv/gerrit/git/All-Users.git

$ git ls-tree refs/users/34/1234
100644 blob xxx account.config
100644 blob yyy authorized_keys
100644 blob zzz preferences.confg
100644 blob ddd watch.config

$ git show refs/users/34/1234:authorized_keys
ssh-rsa AAAAxyz... RSA-1024

The All-Users database can be browsed locally via git. The easiest way to find a user given the All-Users git repo is to git-grep for the username or email in the refs/meta/external-ids ref:

$ mkdir All-Users && cd All-Users && git init
$ git pull refs/meta/external-ids
$ git grep johndoe

Disabling / Blocking / Unblocking an account

These actions are limited to Gerrit administrators.

Determine the user id

First find the user id of the account:

$ ssh -p 29418 gerrit ls-user-refs --project All-Users --user '' 
Account '' only matches inactive accounts. To use an inactive account, retry with one of the following exact account IDs:
54321: John Doe <>

In this case the user id is 54321.

Disable User

If an account needs to be disabled for some reason, there's two steps to complete:

  • remove the ssh keys
  • set the account to inactive

To set an account inactive, use this command:

$ ssh -p 29418 gerrit set-account --inactive <user id here>

Unblock/Reenable User

To enable the user again:

$ ssh -p 29418 gerrit set-account --active <user id here>

Flush replica cache

After altering a user account, flush the accounts cache on the replica:

$ ssh -p 29418 gerrit flush-caches --cache accounts

Flush all sessions

Flushing web_sessions caches makes everyone re-login (aka, the sledgehammer). It should not be necessary in most circumstances; however, the command is still in this documentation in case it is needed in an unforeseen situation:

$ ssh -p 29418 gerrit flush-caches --cache web_sessions

Tasks management

Gerrit queue tasks, given you have the appropriate permission you can run either of:

$ ssh -p 29418 ps -w
$ ssh -p 29418 gerrit show-queue -w

Tasks can be stuck which starve Gerrit processing. For example people would no more be able to fetch. In such a case, granted you are in the Administrators group you can kill a task by id:

$ ssh -p 29418 kill <SOMEID>


Forcing Replication re-runs

When forcing a replication run through gerrit's replication plugin, stay clear of the --all switch, as it breaks renamed projects on github.

For example, both gerrit and github have a mediawiki repository. But github's mediawiki repository is actually mediawiki/core in gerrit. As gerrit also has a mediawiki repository, forcing replication on all projects would push gerrit's mediawiki repository onto github's mediawiki repository. Thereby, github's mediawiki repository falls over, and for examples the release tags from github's mediawiki are gone (cf. task T100409).

This currently (2015-05-28) affects us for at least for the following repos:

Gerrit's name Overloaded name on GitHub
mediawiki/core mediawiki
VisualEditor/VisualEditor VisualEditor
oojs/core oojs

If you by accident forced replication with --all, force replication of the effective gerrit repos to make up for it (i.e.: mediawiki/core, VisualEditor/VisualEditor, ...)


The group mediawiki-replication must be allowed to read refs/tags/* and refs/heads/* for replication to GitHub to work. This is because it is currently set as the authGroup in replication.config inside etc inside the Gerrit repository home.

Additionally, the replication_log should be checked in addition to the gerrit.log for mention of anything that could be wrong with replication.

Any changes to replication.config should be followed with a restart of the gerrit service to ensure that those changes are active. There is a bug with the replication plugin where it will reload the replication.config (and acknowledge that the configuration has been reloaded in the logs), but actually operate with a broken configuration in an unknown state until a restart.


As of July 2018 replication to github requires a repository to be manually created on github using the naming scheme gerrit expects, i.e. / replaced with - (FrEx: operations/debs/trafficserver -> operations-debs-trafficserver.

Github owners will be able to create these repositories.

Once a repository is created, replication to that repo can be forced using the gerrit replication ssh command.

$ ssh -p 29418 replication start operations/debs/trafficserver --wait


ORES mirroring setup is dangerous and unusual, but should, nevertheless, be documented.

The canonical repository for ORES lives on github. This is repository is observed by diffusion. This can done in the Manage Repository section of diffusion code browser. From there, phabricator "Mirrors" that repository (also available in diffusion management settings) to gerrit.

This setup is discouraged.