TeamCity allows the two-way synchronization of the project settings with the version control repository. Supported VCSs are Git, Mercurial, Perforce, Subversion, and since TeamCity 10.0, TFS.
On this page:
Note that SSH keys will not be stored in the VCS repository.
When you enable two-way settings synchronization:
- each administrative change made to the project settings in the TeamCity Web UI is committed to the version control; the changes are made noting the TeamCity user as the committer;
- if the settings change is committed to the version control, the TeamCity server will detect the modifications and apply them to the project on the fly.
Before applying the newly checked-in settings, certain constraints are applied. If the constraints are not met (i.e. the settings are invalid), the current settings are left intact and an error is shown in the UI. Invalid settings are those that cannot be loaded because of constraints, for instance, a build configuration referencing a non-existing VCS root, of having a duplicate id or a duplicate name, etc.
The settings in the VCS are stored in the
.teamcity folder in the root of the repository the same format as in the TeamCity Data Directory.
Synchronizing Settings with VCS
By default, the synchronization of the project settings with the version control is disabled.
To enable it, go to Project Settings | Versioned Settings.
The "Enable/disable versioned settings" permission is required (default for the System Administrator role).
The Configuration tab is used to define:
- whether the synchronization settings are the same as in the parent project
- whether the synchronization is enabled.
- when synchronization is enabled, you can define which settings to use when build starts. See details below.
which VCS Root is used to store the project settings: you can store the settings either in the same repository as the source code, or in a dedicated VCS root.
Enabling synchronization for a project also enables it for all its subprojects. TeamCity synchronizes all changes to the project settings (including modifications of build configurations, templates, VCS roots, etc.) with the exception of SSH keys.
You can override the synchronization settings inherited from a project for a subproject.
As soon as synchronization is enabled in a project, TeamCity will make an initial commit in the selected repository for the whole project tree (the project with all its subprojects) to store the current settings from the server. If the settings for the given project are found in the specified VCS root (the VCS root for the parent project settings or the user-selected VCS root), a warning will be displayed asking if TeamCity should:
- overwrite the settings in VCS with the current project settings on the TeamCity server
- import the settings from VCS replacing the the current project settings on the TeamCity server with those from version control
Defining Settings to Apply to Builds
There are 2 sources of build settings: the current settings on the TeamCity server, i.e. the latest settings changes applied to the server (either made via the UI, or via a commit into the .teamcity directory in the VCS root) and the settings in the VCS on the revision selected for build.
- if you are using TeamCity feature branches, you can define a branch specification in the VCS root used for versioned settings, and TeamCity will run a build in a branch using the settings from this branch
- you can now start a personal build with changes made in the
.teamcitydirectory, and these changes will affect the build behavior.
- When running a history build, TeamCity will attempt to use the settings corresponding to the moment of the selected change. Otherwise, the current project settings will be used.
Before starting a build, TeamCity stores configuration for this build in build internal artifacts under
.teamcity/settings directory. These configuration files can be examined later to understand what settings were actually used by the build.
To define which settings to take when build starts, select one of the following options (on the Project Settings | Versioned Settings page, Configuration tab, click Show advanced options):
- always use current settings: when this option is set, all builds use current project settings from the TeamCity server. Settings changes in branches, history and personal builds are ignored. Users cannot run a build with custom project settings.
- use current settings by default: when this option is set, a build uses the latest project settings from the TeamCity server. Users can run a build with older project settings via the custom build dialog.
- use project settings from VCS:
when this option is set, builds in branches and history builds, which use settings from VCS, load settings from the versioned settings revision calculated for the build. Users can change configuration settings in personal builds from IDE or can run a build with project settings current on the TeamCity server via the custom build dialog.
Limitations of "use project settings from VCS" mode
There are some limitations when the "use project settings from VCS" option is selected and a build on a branch, or a personal, or a history build is run. Certain settings will be ignored and current settings will be used instead. This applies for:
- VCS roots and checkout rules
- Snapshot dependencies
- Certain build Failure Conditions and Build Features which are processed on the server-side (like fail build on message, automatic merge and VCS labeling)
- Build Configuration-level settings not affecting the build directly, like Build Triggers or number of simultaneously running builds
You can select the settings format: on the Versioned Settings | Configuration page for your project, click Show advanced options.
TeamCity stores project settings:
- in the
since TeamCity 10 in
kotlin-based DSL(see a dedicated page).
Committing current project settings to VCS
If you want to commit the current configuration to the VCS (e.g. earlier you committed misconfigured settings to the repository and TeamCity was unable to load it displaying errors and warnings), you can use the Commit current project settings... option on the Versioned Settings | Configuration page.
TeamCity will not only synchronize the settings, but will also automatically display changes to the project settings the same way it is done for regular changes in the version control. You can configure the changes to be displayed for the affected build configurations: on the Project Settings | Versioned Settings page, Configuration tab, click Show advanced options and check the Show settings changes in builds box.
By default, the VCS trigger will ignore such changes. To enable build triggering on a settings commit, add a trigger rule in the following format:
All changes in the VCS root where project settings are stored are listed on the Versioned Settings | Change log tab of the Versioned Settings page.
Q. Can I apply the settings from a TeamCity server of a different version?
A. No, because just like with the TeamCity Data Directory, the format of the settings differs from one TeamCity version to another.
Q. Where are the settings stored?
A. The settings are stored in the
.teamcity directory relative to the configured client.
Q. Why is there a delay before a build is run after I changed to the settings in the UI?
A. When the settings are changed via the UI, TeamCity will wait for the changes to be completed with a commit to the VCS before running a build with the latest changes.
Q. Who are the changes authored by?
A. If the settings are changed via the user interface, in Git and Mercurial a commit in the VCS will be performed on behalf of the user who actually made the change via the UI. For Perforce as well as TFS, the name of the user specified in the VCS root is used, and in Subversion the commit message will also contain the username of the TeamCity user who actually made the change via the UI.