Storing Project Settings in Version Control
Since TeamCity 9.0, TeamCity allows the two-way synchronization of the project settings with the version control repository (Git or Mercurial, and since TeamCity 9.1, Perforce and Subversion).
Security Implications
Enabling storing settings in VCS has some security implications and it is recommended to carefully consider those before deciding on the scope of the feature use.
being able to change the settings in an arbitrary manner via VCS, it is possible to trigger builds of any build configurations and obtain settings of any build configurations irrespective of the build configurations permissions configured in TeamCity
by committing wrong or malicious XML settings, a user can affect the entire server performance or server presentation to other users.
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 System Administrator).
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.
It is recommended to create a VCS repository dedicated to the setting storage due to security implications. If the settings contain passwords, a separate repository with a limited access provides better security.
When synchronization is enabled:
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 are altered in the version control, the TeamCity server will detect the modifications and apply them to the project on the fly.
The settings in the VCS are stored in the same format as in the TeamCity Data Directory. The format of the settings differs from one TeamCity version to another.
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 on the Versioned Settings | Configuration page of 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 current project settings on the TeamCity server with those from the version control
The settings are stored in the .teamcity folder in the root of the repository; the default branch is used with Git and Mercurial.
If you wish to change the path used by TeamCity, you can create a special VCS Root dedicated to the VCS settings storage, and specify the path as you want there. TeamCity will use the .teamcity directory relative to the configured client.
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.
If the settings are changed via the user interface, a commit in the VCS will be performed on behalf of the user specified in the VCS root. For Perforce and Subversion the commit message will also contain the username of the TeamCity user who actually made the change via the UI.
Defining Settings to Apply to Builds
Since TeamCity 9.1, you can 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:
if you are starting a history build, TeamCity will use the settings corresponding to the moment of the selected change
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.
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:
always use current settings: when this option is set, 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, a build loads settings from the versioned settings revision calculated for the build. This includes builds in branches and history builds, which use settings from VCS. 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.
There are a few limitations when using settings from the VCS:
changes in snapshot dependencies will be ignored, TeamCity will continue reading snapshot dependencies settings from the build configuration
changes in build failure conditions and build features working on the server (like automatic merge and labeling) are ignored too
changing some of the settings does not make much sense for build, for instance, build triggers, general settings like limitation on a number of concurrently running builds, and some others.
Forcing Synchronization
To force synchronization of the current project settings, use the Commit current project settings... option on the Versioned Settings | Configuration page.
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. Such changes are ignored by build triggers.
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.
Known Limitations
The supported version controls are Git and Mercurial, and since TeamCity 9.1, Perforce and Subversion.
When running a history build in TeamCity, the current project settings will be used. Since TeamCity 9.1, TeamCity will attempt to use the settings corresponding to the moment of the selected change. For details, see the section above.
Project settings may contain scrambled passwords. Once you enable settings synchronization, everyone who has a developer role in the project will be able to see these passwords using the changes difference viewer.