TeamCity On-Premises 2026.2 Help

Projects Import

Projects Import adds projects with all their data and user accounts from a backup file to an existing TeamCity server, effectively merging two servers into one.

Projects Import or Server Move

Import is a disruptive operation and not all data is imported, so use it only when you need to add projects to a server that already hosts other projects. To move all the data of a server to a different machine, use server move instead.

Importing projects

  1. On the source server, create a usual backup file containing the projects to import. The major version of the source and target servers must be the same.

  2. On the target server, go to Server Administration | Project Import, upload the backup file, and follow the wizard. TeamCity displays the results when the import finishes.

Selecting projects for import

After selecting a backup file, choose which projects to import. TeamCity analyzes them and reports whether each project will be imported, merged, or skipped.

  • The project is imported if it is new for the target server. All its entities (build configurations, templates, builds, and so on) and their data are created on the target server.

  • The project is merged if it already exists on the target server, that is, the source and target projects share the same UUID and external ID. Existing entities remain intact, and only the entities that are new for the target are imported with their data.
    Data of the existing entities is neither imported nor merged: new changes are not added to an existing VCS root, and a template that exists on both servers keeps its target settings. This also means you cannot import missing builds into an existing build configuration — to do that, delete this build configuration in the UI and reimport its project.

  • The project is skipped if a conflict occurs: its UUID is new but its external ID already exists on the target, or the source and target projects have the same UUID but different external IDs.

Defining import scope

You can import project settings, builds and changes history, and user accounts in any combination. Since an imported project can use settings of its parents, TeamCity also imports the VCS roots, templates, meta-runners, and other project-related settings of the parent projects. Existing objects on the target server are never overwritten.

Configuration files import

For each imported or merged project, TeamCity copies the configuration files that are new for the target server to its Data Directory. Existing files are not changed.

The following files are imported:

  • Configuration XML files of 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 number files of the newly added build configurations.

Importing users, groups, and tokens

User accounts

TeamCity users must have unique usernames, so when users are in the import scope, TeamCity compares usernames to see whether each user will be imported or merged. In both cases, it transfers all the user-related data (personal builds, changes, test mutes, and investigations) and the user account settings — roles, permissions, VCS names, notification settings, and so on, both system-wide and related to the imported projects.

  • A user whose username is new for the target server is imported. Such users appear on the target server in a separate group marked Imported <Import Date Time>.

  • A user whose username exists on both servers can be merged. The existing data remains intact, and only the data that is new for the target is added.

Merging relies on usernames, so if the same username belongs to different people on the two servers, their information is merged anyway. Merging can also extend a user's permissions on the target server: a system administrator role granted on the source server is added to the target user, while project roles are added only for the projects within the import scope.

The Project Import | Import scope | Users section reports how many conflicts were found, so that you can review them and decide whether to merge. TeamCity lists users that have the same username but different emails on both servers, and counts users that share both a username and an email. If email verification is enabled, such users are compared based on their verified emails. These options are active only when users with verified emails are present on the source server, the target server, or both.

User groups

Groups work the same way: new groups are imported and the existing ones can be merged. If a conflict occurs — a group exists on both servers but with different roles — the target group may get additional roles after the import, and so do all its members.

The Project Import | Import scope | Groups section reports how many conflicting groups were found. You can view all groups that share a group key and decide whether to merge them. The "All Users" group is always listed as conflicting because it exists on every TeamCity server by default.

Access tokens

When users are in the import scope, whether TeamCity transfers their access tokens depends on the token scope:

  • Tokens limited to the projects selected for import (the Limit per project scope) are imported by default. On the target server, these tokens retain their permissions only for the imported projects.

  • Tokens limited to any other project are not imported. This has the following effects:

    • If a token is scoped for project A (imported) and project B (no imported), its permission scope narrows down to A.

    • If a token is scoped for multiple projects, none of which were imported, the token is not imported at all.

    • A token scoped to the parent project of an imported project is skipped, even though TeamCity imports the settings this parent project shares with its children.

  • Tokens that grant the same permissions as their owner (the Same as current user scope) are imported only with explicit consent: select the corresponding checkbox in the Project Import | Import scope | Users section. Since such tokens are not limited to any project, on the target server they grant every permission that their owner has there — which is why they are left out by default.

For a merged user, imported tokens are added to the tokens that this user already has on the target server. If a user already has a token with the same name, the matching imported token is skipped.

Conflicts

TeamCity does not import entities from the backup file if they conflict with an entity on the target server. Before the import, TeamCity analyzes the backup file and displays all detected conflicts on the Import Scope configuration page.

It is highly recommended that you resolve all conflicts before proceeding, as unresolved conflicts may result in unpredictable behavior after the import. For example, a build configuration can report a critical error if the VCS root it depends on was skipped, or refer to the wrong template if the templates from the source and target servers had conflicting external IDs.

If you import without resolving the conflicts, you can find the conflicting files in the conflictingFiles directory under the import results logs.

Data not included into import

The import has the following limitations:

  • Agents and agent pools are not imported (TW-39797).

  • Settings are merged on a per-file basis: new files are added, but no settings files are merged. For example, if a project being imported already exists on the target server, its parameters, project features, and plugin settings are not merged.

  • If you use the "Store secure values (like passwords or API tokens) outside of VCS" option for versioned settings, credentials are not imported for the projects that already exist on the server.

  • Audit records are imported only if users are in the import scope.

  • Running builds and the build queue are not included in the backup, and thus not imported.

  • Internal IDs, such as build IDs, are not preserved. This means that URLs to the build results pages from the old server appear broken even if redirected to the new server.

  • Backup files do not contain artifacts and logs (build logs are stored under build artifacts), so these are not imported automatically. TeamCity provides scripts to move them manually.

  • Global server settings (authentication schemes, custom roles, and so on) are not imported.

  • Build artifacts and logs cannot be imported to TeamCity Cloud.

Moving artifacts and logs

Artifacts and logs are not imported from the backup file, but you can copy or move them from the source to the target server using the .bat and .sh scripts from the projectsImport-<date> directory under the TeamCity logs. These scripts accept the source and target artifact directories via the command line, and the rest is done automatically. You can run the scripts while the server is running.

It may take some time for TeamCity to display the imported build artifacts.

Viewing Import Results

Each import process creates the projectsImport-<date> directory under the TeamCity logs, allowing you to view the import results. This directory contains:

  • the conflictingFiles directory with all the data that has been merged

  • mappings of the fields in the source and target databases

  • scripts for copying artifacts and logs (see the section above)

  • the import report listing the import results, including the information on the data that has not been imported (if any)

27 August 2026
Project ExportConfiguring VCS Settings