Projects Import
TeamCity allows you to import projects with all their data and user accounts from a backup file to an existing TeamCity server. This approach should only be used when the task is to add projects from one server to another server when the target server is normally used. Otherwise, consider using entire server move.
To import projects:
On the source TeamCity server:
Create a usual backup file containing the projects to be imported (the major and minor versions of the source and target TeamCity servers have to be the same)
On the target TeamCity server:
Go to the Server Administration area and select Project Import on the left. Upload your project settings and follow the wizard. When the import finishes, TeamCity will display the results.
Importing projects
After selecting a backup file, you need to specify which projects will be imported.
TeamCity will analyze the selected projects to see if they will be imported, merged or skipped.
The project will be imported if it is new for the target server. All its entities (Build Configurations, Templates, Builds, etc) and their data will be created on the target server.
The project will be merged if the same project already exists on the target server (if the source and target project have the same UUID and external ID). During merging the existing entities will remain intact and only the entities new for the target will be imported with the related data. The data for the existing entities will not be imported or merged: new data will not be added to the existing entities (e.g. changes will not added to an existing VCS root), the existing files will not be changed (e.g. if the same template exists on both servers with different settings, the target file will be preserved). It means, for example, that you cannot import missing builds to the existing build configuration. If you need to add the missing data to the existing entities, for example, import new builds into an already imported build configuration, then you should remove this build configuration using the UI and re-import its project.
The project will be skipped if a conflict occurs: either the project's UUID is new but its external ID already exists on the target; or if the source and target projects have the same UUID but different external IDs.
Defining import scope
You can select the import scope: choose among project settings, builds and changes history, and user accounts or import all of them. Since an imported project can also use settings from its parent, TeamCity will also import all the vcs roots, templates, meta-runners and other project-related settings for parent projects. If the same project already exists on the target server, the existing objects will not be overwritten.
Configuration files import
For each imported or merged project, the configuration files are imported to the data directory on the target server, provided they are new for the target. The existing files will not be changed.
The following files are imported:
Configuration xml files for the Project with its Build Configurations, Templates, and VCS Roots as well as its subprojects.
All files from the
<TeamCity Data Directory>/pluginsdirectory.Build Numbers files for the newly added build configurations.
Importing users and groups
Users
When users are selected for import, TeamCity will analyze the usernames to see if users will be imported or merged.
TeamCity users must have unique usernames.
Import: A user account whose username is new for the target server will be imported. Such users appear on the target server in a separate group marked Imported <Import Date Time>. All the related data (personal builds, changes, test mutes and investigations) will be created on the target server. The user account settings (roles, permissions, VCS names, notification settings, etc.: system-wide settings as well as the settings related to the imported projects) are preserved during import.
Merging: User accounts with the same username on the source and the target servers can be merged. During merging the existing data will remain intact and only the data new for the target will be added: all the new user-related data (personal builds, changes, test mutes and investigations) and the user account settings (roles, permissions, VCS names, notification settings, etc.: system-wide settings as well as the settings related to the imported projects) will be added to the user on the target server. Merging may cause a problem if the same username belongs to different users on the source and the target server: during import the user information will be merged anyway.
Note that the scope of user permissions on the target may change after import, e.g.
if a user has the system administrator role on the source, this role will be added to the user on the target after import,
if a user has several roles in several projects on the source, only the new roles for the projects within the import scope will be added on the target.
The Project Import page | The Import scope section | Users will display the number of conflicts and you can view them and decide if you want to merge them. TeamCity will show users with the same username and different emails on both servers, as well as the number of users with the same username and the same email.
Email verification can be enabled for the server, and the users with the same username and email are compared based on their email verification. You can view the conflicts information and choose whether to merge the users found. The options are active if users with verified emails are present either on the source or the target TeamCity server, or both.
Groups
Import of user groups works the same way: new groups are imported, while the existing groups can be merged.
If a conflict occurs (the groups exists on both the source and the target, but the group roles are different), after import the group on the target server may get additional roles. As a result, a member of this group on the target will get additional roles and permissions as well.
The Project Import page | The Import scope section | Groups will display how many conflicting groups are found. You can view all the groups that have the same group key and decide if you want to merge them. Note that "All Users" group is always listed as a conflicting one because it is a default group on all TeamCity servers.
Conflicts
TeamCity does not import entities from the backup file if they conflict with some entity on the target server. Before import, TeamCity analyzes the backup file and displays all detected conflicts on the Import Scope configuration page.
It is highly recommended to resolve all conflicts before proceeding with the import, as unresolved conflicts may result in unpredictable behavior after the import, e.g.:
Critical errors can be shown if, for example, some VCS Root was skipped, but a Build Configuration depending on it was imported.
Imported Build Configurations may refer to the wrong Template if there was an unresolved conflict of external IDs between the templates from the source and target servers.
Data excluded from import
There is a number of limitations regarding the import of project-related data:
audit records are imported only if users are selected in the scope;
the backup files do not contain artifacts and logs (since version 9.0 build logs are stored under build artifacts), so these are not imported automatically, but TeamCity provides scripts to move them manually;
running builds and the build queue are not included in the backup and not imported;
global server settings (authentication schemes, custom roles, etc.) are not imported;
internal ids (like ids of the builds) are not preserved during import. This means that URLs to the build results pages from the old server will appear broken even if redirected to the new server as build ids change on importing.
Viewing Import Results
Each import process creates the projectsImport-<date> directory under the TeamCity logs allowing you to view the import results.
The directory contains the following:
conflicting files folder, containing all data which has been merged
mappings, containing mapping of the fields in the source and target databases
scripts for copying artifacts and logs (see the section below)
import report, listing import results including the information on the data which has not been imported (if any)
Moving artifacts and logs
Although artifacts and logs are not imported right from the backup file, you can copy/move them from the source to the target server using the .bat and .sh scripts from the projectsImport-<date> directory under TeamCity logs. These scripts accept the source and target data directories via the command line; since TeamCity 9.1 the scripts accept the source and target artifact directories. The rest is done automatically. The scripts can be executed while the server is running.
It may take some time for TeamCity to display the imported build artifacts.