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:

gerrit2 system user
LDAP group gerritadmin (member list)

Administrator right is thus granted by adding a user to the LDAP group using the LDAP approval procedure.

Note: LDAP groups membership is cached for 1 hour (as of September 2026). If needed, an administrator can flush the cache using:

$ ssh -p 29418 gerrit.wikimedia.org gerrit flush-caches --cache ldap_groups

If right is given as a one off, the user should be removed from the group once the rights are no longer required.

Creating new repositories

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

Users without administrative access to Gerrit can request a repository to be created on mw:Gerrit/New repositories.

Determine version of Gerrit running

To find out what version of Gerrit is running live, from your machine:

$ ssh -p 29418 gerrit.wikimedia.org gerrit version

On the server

$ java -jar /var/lib/gerrit2/review_site/bin/gerrit.war version

Inspecting an account settings

Accounts are stored in the repository All-Users.git (see accounts documentation ).

To act on an account, find the git reference pointing to the user account data. It is done by checking which references a user is permitted to 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

The user johndoe@wikimedia.org is able to read:

refs/meta/config: configuration of the repository itself
refs/users/34/1234: reference for that specific user
refs/users/self: convenience alias to the previous user ref

Accounts having extended permissions on All-Users.git, all references will be returned.

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

Monitoring of replication is provided by the Grafana dashboard: Gerrit > Replication.

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 a Gerrit replica named gerritXXXX (DO NOT USE FOR GitHub):

ssh -p 29418 gerrit.wikimedia.org replication start --now --url gerritXXXX

You can pass --wait to have it run in foreground.

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.

Tracked in Phabricator
Task T416929

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. The most likely cause of a changed replication.config would be an operations/puppet.git patch changing the profile::gerrit::replication hiera settings.

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