diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index 738476e912..545c3a008c 100644 --- a/doc/source/gerrit.rst +++ b/doc/source/gerrit.rst @@ -453,161 +453,74 @@ API documentation. .. _create-account: https://review.opendev.org/Documentation/cmd-create-account.html -Resetting a Username in Gerrit ------------------------------- - -Initially if a Gerrit username (which is used to associate SSH -connections to an account) has not yet been set, the user can type -it into the Gerrit WebUI... but there is no supported way for the -user to alter or correct it once entered. Further, if a defunct -account has the desired username, a different one will have to be -entered. - -Because of this, often due to the user ending up with `Duplicate -Accounts in Gerrit`_, it may be requested to change the SSH username -of an account. Confirm the account_id number for the account in -question and remove the existing username external_id for that (it -may also be necessary to remove any lingering external_id with the -desired username if confirmed there is a defunct account associated -with it): - -.. code-block:: mysql - - delete from account_external_ids where account_id=NNNN and external_id like 'username:%'; - -After this, the user should be able to re-add their username through -the Gerrit WebUI. +Deleting Accounts in Gerrit +--------------------------- +We can not delete accounts. They can be made inactive. Duplicate Accounts in Gerrit ---------------------------- -From time to time, outside events affecting SSO authentication or -identity changes can result in multiple Gerrit accounts for the same -user. This frequently causes duplication of preferred E-mail -addresses, which also renders the accounts unselectable in some -parts of the WebUI (notably when trying to add reviewers to a change -or members in a group). Gerrit does not provide a supported -mechanism for `Combining Gerrit Accounts`_, and doing so manually is -both time-consuming and error prone. As a result, the OpenStack -infrastructure team does not combine duplicate accounts for users -but can clean up these E-mail address issues upon request. To find -the offending duplicates: +If a user has two accounts, we can not combine them. We can only +deactivate one of them. -.. code-block:: mysql +For example, user ``foo`` has an account ``foo@company.com`` and moves +to a new job, creating a new account ``foo@new.com``. They log-in +with ``foo@new.com``, but then realise what they really wanted to do +was *add* this new address to their existing account +(i.e. ``foo@company.com``). - select account_id from accounts where preferred_email='user@example.com'; +The first step to resolve this is to confirm the ID of the unwanted +account, . As an admin user with a HTTP password set, search for the +new account: -Find out from the user which account_id is the one they're currently -using, and then null out the others with: +.. -.. code-block:: mysql + curl -u you.admin -i -H "Accept: application/json" 'https://review.opendev.org/a/accounts/foo@new.com' - update accounts set preferred_email=NULL, registered_on=registered_on where account_id=OLD; +That will return an ``_acount_id``. For this example, assume it is +``12345``. The user should check in their settings they are *not* +using this account. -Then be sure to set the old account to inactive: +Clone ``All-Users`` to modify the account, and checkout the account +config, which is sharded by the last two digits of the account-id. -.. code-block:: bash +.. - ssh review.opendev.org -p29418 gerrit set-account --inactive OLD + git clone ssh://you.admin@review.opendev.org:29418/All-Users + git fetch refs/users/45/12345 + git checkout FETCH_HEAD -Finally, flush Gerrit's caches so any immediate account lookups will hit -the current DB contents: +Edit the ``[account]`` section of ``account.conf`` to remove +``preferredEmail`` and have a line ``active = false``. Put your admin +account into ``Project Bootstrappers`` (see :ref:`sysadmin`) and +commit this -.. code-block:: bash +.. - ssh review.opendev.org -p29418 gerrit flush-caches --all + git commit -m "Make duplicate account inactive" --author + git push origin HEAD:refs/users/45/12345 +There will still be an OpenID external ID associated with this now +inactive account. This will prevent adding ``foo@new.com`` to another +account until this is removed. -Combining Gerrit Accounts -------------------------- +Check this via the API with -While not supported by Gerrit, a fairly thorough account merge is -documented here (mostly as a demonstration of its unfortunate -complexity). Please note that the OpenStack infrastructure team does -not combine duplicate accounts for users upon request, but this -would be the process to follow if it becomes necessary under some -extraordinary circumstance. +.. -Collect as much information as possible about all affected accounts, -and then go poking around in the tables listed below for additional -ones to determine the account_id number for the current account and -any former accounts which should be merged into it. Then for each -old account_id, perform these update and delete queries: + curl -u you.admin -i -H "Accept: application/json" https://review.opendev.org/a/accounts/12345/external.ids -.. code-block:: mysql +This will give a json result with an ``identity`` URL like +``"identity":"https://login.ubuntu.com/+id/RaND0m``. Use this to +delete the record with another call - delete from account_agreements where account_id=OLD; - delete from account_diff_preferences where id=OLD; - delete from account_external_ids where account_id=OLD; - delete from account_group_members where account_id=OLD; - delete from account_group_members_audit where account_id=OLD; - delete from account_project_watches where account_id=OLD; - delete from account_ssh_keys where account_id=OLD; - delete from accounts where account_id=OLD; - update account_patch_reviews set account_id=NEW where account_id=OLD; - update starred_changes set account_id=NEW where account_id=OLD; - update change_messages set author_id=NEW, written_on=written_on where author_id=OLD; - update changes set owner_account_id=NEW, created_on=created_on where owner_account_id=OLD; - update patch_comments set author_id=NEW, written_on=written_on where author_id=OLD; - update patch_sets set uploader_account_id=NEW, created_on=created_on where uploader_account_id=OLD; - update patch_set_approvals set account_id=NEW, granted=granted where account_id=OLD; +.. -If that last update query results in a collision with an error -like:: + curl -XPOST -u you.admin -i -H "Content-Type: application/json" -d '["https://login.ubuntu.com/+id/RaND0m"]' https://review.opendev.org/a/accounts/12345/external.ids:delete - ERROR 1062 (23000): Duplicate entry 'XXX-YY-NEW' for key 'PRIMARY' - -Then you can manually delete the old approval: - -.. code-block:: mysql - - delete from patch_set_approvals where account_id=OLD and change_id=XXX and patch_set_id=YY; - -And repeat until the update query runs to completion. - -After all the described deletes and updates have been applied, flush -Gerrit's caches so things like authentication will be rechecked -against the current DB contents: - -.. code-block:: bash - - ssh review.opendev.org -p29418 gerrit flush-caches --all - -Make the user aware that these steps have also removed any group -memberships, preferences, SSH keys, CLA -signatures, and so on associated with the old account so some of -these may still need to be added to the new one via the Gerrit WebUI -if they haven't been already. With a careful inspection of all -accounts involved it is possible to merge some information from the -old accounts into new ones by performing update queries similar to -the deletes above, but since this varies on a case-by-case basis -it's left as an exercise for the reader. - - -Deleting a User from Gerrit ---------------------------- - -This isn't normally necessary, but if you find that you need to -completely delete an account from Gerrit, perform the same delete -queries mentioned in `Combining Gerrit Accounts`_ and replace the -update queries for account_patch_reviews and starred_changes with: - -.. code-block:: mysql - - delete from account_patch_reviews where account_id=OLD; - delete from starred_changes where account_id=OLD; - -The other update queries can be ignored, since deleting them in many -cases would result in loss of legitimate review history. - -Refreshing HTML and CSS configuration -------------------------------------- - -When there is a change in HTML headers, or CSS, this can be applied -without the need of restarting Gerrit. To do that, ssh in the Gerrit -instance, and touch GerritSiteHeader.html and/or GerritSite.css, -under /home/gerrit2/review_site/etc directory. +The user should now be able to add ``foo@new.com`` to their old +account. Deactivating a Gerrit account -----------------------------