On this page:

Overview

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.

You can store settings in the XML format and, since TeamCity 10.0, in the Kotlin language and define settings programmatically using the kotlin-based DSL

When you enable two-way settings synchronization:  

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.   

(info) The "Enable/disable versioned settings" permission is required (default for the System Administrator role).

The Configuration tab is used to define:

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.

(info) 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:

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.

Therefore it is possible to start builds with settings different from those currently defined in the build configuration. For projects where versioned settings are enabled, you can tell TeamCity which settings to take when build starts.
This gives you several possibilities:

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 tabclick Show advanced options):

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:

See also internal details at: https://confluence.jetbrains.com/display/TCINT/Versioned+Settings+Freeze

Storing Secure Settings 

It is recommended to store security data outside the VCS. Since TeamCity 2017.1, the Project Settings | Versioned Settings | Configuration page has an option to store passwords, API tokens, and other secure settings outside of VCS. This option is enabled by default if versioned settings are enabled for a project for the first time, and not enabled for projects already storing their settings in the VCS.

If this option is enabled,TeamCity stores a random generated ids in xml configuration files instead of the scrambled passwords.  Actual passwords are stored on the disk under TeamCity data directory and are not checked into the version control system.

If this option is not enabled, the security implications listed below should be taken into account before committing security data to the VCS.

Generating Tokens 

When you need to add a password into the versioned settings not via TeamCity UI (e.g. adding settings with Kotlin-based DSL), you will need to add the password to TeamCity and get the corresponding token to use in the settings. The token can be generated via the "Generate Token for password" action available in the Project -> Actions menu. 

At this time passwords are not inheritable by projects hierarchy. If a setting in a project  (a VCS root, OAuth connection, cloud profile) requires a password, the token generated for this password can be used in this project only. For instance, it is not possible to take a generated token and use it ain a similar setting in a subproject. A new token should be generated in this case.
If you need to use a secure value in the nested projects, consider adding a password parameter with the secure value and using a reference to the parameter in the nested projects.


Implications of Storing Security Data in VCS 


If you are using a version prior to TeamCity 2017.1, it is recommended to carefully consider the implications of storing security settings in a VCS.

It is recommended to store passwords, API tokens, and other secure settings outside of VCS using the corresponding option described above.

Note that SSH keys will not be stored in the VCS repository.

Settings Format

You can select the settings format: on the Versioned Settings | Configuration page for your project, click Show advanced options

TeamCity stores project settings:

Committing Current Project Settings to VCS

Before committing settings to the VCS, consider the recommended approach to storing security settings described above.


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.

When TeamCity commits settings into a VCS, it uses a  standard commit message noting the TeamCity user as the committer and the project whose settings changed. Since TeamCity 10.0, it is possible to add a fixed custom prefix to each settings change commited by TeamCity via the teamcity.versionedSettings.commitMessagePrefix internal property, e.g. teamcity.versionedSettings.commitMessagePrefix=TC Change\n\n

Displaying Changes

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 tabclick 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: +:root=Settings_root_id;:*

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.

Enabling Versioned Settings after TeamCity Upgrade

The format of the XML settings files changes from one TeamCity version to another to accommodate the new features and improvements. Generally, the format is not changed within bugfix releases and is changed in minor/major releases. When a TeamCity server is upgraded, the current settings on the TeamCity server are changed from the earlier to the current format.

It is a common practice to upgrade a TeamCity test server with production data before upgrading the production server. In order to avoid accidentally changing the format of the settings which are used on a production server of an older version, versioned settings are disabled after a TeamCity upgrade and the corresponding health item is displayed. System administrators have permissions to enable versioned settings. When enabled, the converted settings in the format of the current TeamCity version will checked in the the version control. Note that the new settings will be committed to the default branch of the VCS root; the settings stored in other branches will have to be updated manually.

FAQs

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 folder in the root of the VCS root-configured repository path. For Git and Mercurial this is always the root of the repository. The default branch configured in the VCS root is used with GitMercurial. You can create a dedicated VCS root to change the branch (or a repository path in case of Perforce, Subversion or TFS).

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.




See also:

Administrator's Guide: Kotlin DSL