Projects Import
Since TeamCity 9.0, you can import projects with all their data and user accounts from a backup file to an existing TeamCity server.
To start importing projects:
create a usual backup file on the source TeamCity server containing the projects to be imported (note that the major and minor versions of the source and target TeamCity servers have to be the same)
put the backup file into the
<>/importdirectory on the target serverfollow the import steps on the Administration| Projects Import page.
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 exisitng 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
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.
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.
User accounts with the same username on the source and the target servers will be automatically 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 - since TeamCity 9.0.1, 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. Automatic 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 changed 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.
Import of user groups works the same way: new groups are imported, while the existing groups are automatically 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.
Conflicts
TeamCity does not import entities from the backup file if they conflict with some entity on the target server. Since TeamCity 9.0.3, TeamCity analyzes the backup file before import 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
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.