The @PLUGIN@ plugin allows to import projects and groups from a remote Gerrit server into the Gerrit server where the plugin is installed.
The imports are done online while both, source and target Gerrit server, are running.
The user that does the import must be a member of a group that is granted the ‘Import’ capability (provided by this plugin) or the ‘Administrate Server’ capability.
Importing also requires a user/password for the source Gerrit server. This user must be able to see the entities that should imported.
The data for the import is retrieved by accessing the Gerrit REST API on the source Gerrit server. Additionally project imports fetch from the repositories on the source Gerrit server. The git operations are done over the HTTP protocol.
Imports are done in several steps:
Until an import is completed, the imported entities should not be modified in the target Gerrit server, otherwise resuming the import may fail or even override modifications done in the target Gerrit server (e.g. change approvals will be overridden). But depending on what was modified, it may also just work.
Imports are logged in ‘review_site/logs/import_log’ so that administrators can see who imported when which project. Imports do also send audit events.
The import project functionality allows to import (move) a project from one Gerrit server to another Gerrit server.
On project import the configured max object size on the target Gerrit server is ignored.
Draft changes, draft patch sets, change edits and draft comments are not imported.
A project import would be done in several steps:
Doing an initial import first and resuming the import later has the advantage that the downtime for the project team can be kept minimal. The initial project import may take some time, but the resume should be fast since it only needs to transfer the delta since the initial (last) import.
Preconditions for a project import:
For auth type ‘LDAP’, ‘HTTP_LDAP’ or ‘CLIENT_SSL_CERT_LDAP’ missing user accounts are automatically created. The public SSH keys of a user are automatically retrieved from the source Gerrit server and added to the new account in the target Gerrit server. For this the remote user must have the link:access-control.html#capability_modifyAccount[Modify Account] or the link:access-control.html#capability_administrateServer[ Administrate Server] capability assigned on the source system.
If for any reason an user is no longer existent in the LDAP instance but it is listed as a change owner, reviewer or as part of a group, a local user account is created with the same username. Giving that such user is not longer active in the system, their account status is set to inactive.
Gerrit internal users (e.g. service users) should be created in the target Gerrit server before the import. Otherwise, an inactive local user is created with the same username.
All locally created users are added to an internal group called “Imported Users”.
Importing a project can be done via
Resuming a project import can be done via
Completing the import can be done via
When doing a project import the project in the target Gerrit server can be created with a new name or under another parent project.
The project import is implemented in such a way that it replays the actions that have been done in the source Gerrit server with preserving the original timestamps.
A project import consists of the following steps:
Replaying a change is done by:
At a point in time a project can be imported only by a single process. To protect a running import from other processes the import creates an import file ‘review_site/data/@PLUGIN@/<target-project-name>.$importstatus’ and locks this file. In the import file an ImportProjectInfo entity is persisted that stores the input parameters and records the past imports. The import file is kept after the import is done so that the input parameters do not need to be specified again when the import is resumed.
Once a project was imported, the project import can be resumed to import modifications that happened in the source Gerrit server after the initial/last import to the target Gerrit server has been done.
The resume of an import is only guaranteed to work if none of the imported entities has been modified in the target Gerrit server, otherwise resuming the import may fail or even override modifications done in the target Gerrit server (e.g. change approvals will be overridden). But depending on what was modified, it may also just work.
On resume changes that have the same last modified timestamp in the source and target Gerrit server are skipped, unless the force option is set.
The force option is useful if an import finished with warnings (in the error log) and the import should be resumed after fixing the issues, e.g.:
On resume approvals, hashtags and change topic are always reapplied. This means that any modification of these properties in the target Gerrit server is overridden if the import of a change is resumed.
Completing the project import deletes all refs under the ‘refs/imports/’ namespace. In addition the import file for the project is deleted. Afterwards it‘s not possible to resume the project import anymore. Also the project doesn’t appear in the list of imported projects anymore.
Project copy is a special case of project import, where a project from the same Gerrit server is imported under a new name.
To be able to copy a project the user must be a member of a group that is granted the ‘Copy Project’ capability (provided by this plugin) or the ‘Administrate Server’ capability.
Copying a project can be done via
Resuming a project copy can be done via
Completing the copy can be done via
When doing a project copy the project cannot be put under another parent project. But you can reparent the project copy after the copy is done.
By doing a project copy and then using the delete-project plugin to delete the source project, a project can be renamed.
The import group functionality allows to import a Gerrit group from one Gerrit server to another Gerrit server.
The flag whether a group is visible to all registered users is not preserved on import, but the default that is configured for this option on the target Gerrit server is applied to each imported group.
Preconditions for a group import:
For auth type ‘LDAP’, ‘HTTP_LDAP’ or ‘CLIENT_SSL_CERT_LDAP’ missing member accounts are automatically created. The public SSH keys of a member are automatically retrieved from the source Gerrit server and added to the new account in the target Gerrit server.
If for any reason an user is no longer existent in the LDAP instance but it is listed as a group member, a local user account is created with the same username. Giving that such user is not longer active in the system, their account status is set to inactive.
Gerrit internal users (e.g. service users) should be created in the target Gerrit server before the import. Otherwise, an inactive local user is created with the same username.
All locally created users are added to an internal group called “Imported Users”.
If the group name is occupied in the target system (a group with the same name, but a different UUID exists already), the group is automatically imported under the following name: ‘_imported’. If this name is also already occupied an index is appended: ‘_imported_’.
Missing owner groups and missing included groups can be automatically imported into the target Gerrit server.
Importing a group can be done via