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 'email@example.com' 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
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
$ 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 'firstname.lastname@example.org' Account 'email@example.com' only matches inactive accounts. To use an inactive account, retry with one of the following exact account IDs: 54321: John Doe <firstname.lastname@example.org>
In this case the user id is 54321.
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>
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
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
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>
Gerrit runs git garbage collection on all repositories on a daily basis. The logs can be found in
The durations of the last garbage collection can be found via our report utility
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|
If you by accident forced replication with
--all, force replication of the effective gerrit repos to make up for it (i.e.:
mediawiki-replication must be allowed to read
refs/heads/* for replication to GitHub to work. This is because it is currently set as the
etc inside the Gerrit repository home.
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
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 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.