Projects Import

Selecting projects for import

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 (for example, changes will not added to an existing VCS root), the existing files will not be changed (for example, 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>/plugins directory.

• 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, and so on: 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 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, and so on: 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, for example:

  • 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 | Import scope section | Users will display the number of conflicts and you can view them and decide is 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.

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 | 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, for example:

• 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.

If the conflicts have not been resolved before importing, you can find the conflicting files in the conflictingFiles directory under the import results logs.