Gerrit/Administration

Become an Administrator

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.

Gerrit management is granted by the Administrators group which includes the gerrit2 system user and the LDAP group gerritadmin (list of all Gerrit admins in LDAP). To gain Administrator right, one thus has to be added in LDAP (LDAP approval procedure).

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. An administrator can also flush the cache with this command:

$ ssh -p 29418 gerrit.wikimedia.org 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

Gerrit administrators can create repositories using this guide: mw:Git/Creating new repositories.

Those without administrative access to Gerrit should use this guide instead: mw:Gerrit/New repositories.

Determine version of Gerrit running

To find out what version of Gerrit is running, you can use either of the following two commands:

$ java -jar /var/lib/gerrit2/review_site/bin/gerrit.war version
$ ssh -p 29418 gerrit.wikimedia.org gerrit version

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.wikimedia.org gerrit ls-user-refs --project All-Users --user 'johndoe@wikimedia.org' 
refs/meta/config
refs/users/34/1234
refs/users/self

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 https://gerrit.wikimedia.org/r/All-Users 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.wikimedia.org gerrit ls-user-refs --project All-Users --user 'johndoe@wikimedia.org' 
Account 'johndoe@wikimedia.org' only matches inactive accounts. To use an inactive account, retry with one of the following exact account IDs:
54321: John Doe <johndoe@wikimedia.org>

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 gerrit.wikimedia.org -p 29418 gerrit set-account --inactive <user id here>

Unblock/Reenable User

To enable the user again:

$ ssh gerrit.wikimedia.org -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 gerrit-replica.wikimedia.org -p 29418 gerrit flush-caches --cache accounts

Flush all sessions

Do not flush all sessions when banning a single user. As of May 2019 setting a user to inactive should invalidate their session automagically

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.wikimedia.org 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 gerrit.wikimedia.org ps -w
$ ssh -p 29418 gerrit.wikimedia.org 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 gerrit.wikimedia.org kill <SOMEID>

Garbage collection

Gerrit runs git garbage collection on all repositories on a daily basis. The logs can be found in /var/log/gerrit/gc_log.

The durations of the last garbage collection can be found via our report utility gerrit-git-gc-timing.

Replication

Status

You can check the list of replication tasks with:

ssh -p 29418 gerrit.wikimedia.org replication list --detail

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, ...)

Troubleshooting

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.

Github

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 gerrit.wikimedia.org replication start operations/debs/trafficserver --wait

ORES

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.