Skip to end of metadata
Go to start of metadata

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:  

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

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

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

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

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:
  • 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 .teamcity directory, 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 tabclick 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
     

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

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

Icon

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 

For projects with settings in kotlin-based DSL with the option to store security data outside the VCS enabled, it is possible to use tokens instead of passwords.  Tokens can be generated via the "Generate Token for password" action available in the Project -> Actions menu. This action can be useful when project settings are generated via DSL (because the UI is disabled in this case) or if someone wants to change the password not via the user interface, but via a commit into VCS.

For now 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 in a similar setting in a subproject. A new token should be generated in this case. 

Implications of Storing Security Data in VCS 

Storing security settings in VCS has some implications and it is recommended to carefully consider those.

  • If the projects or build configurations with settings in VCS have password fields defined, the values appear in the settings committed into the VCS (though, in scrambled form). 
    • If the project settings are stored in the same repository as the source code, anyone with access to the repository will be able to see these scrambled passwords.

    • If the project settings are stored separately from the source code in a dedicated repository, and the Show settings changes in builds option is enabled, any user having the "View VCS file content" permission can see all the changes in the TeamCity UI using the changes difference viewer.

  • Being able to change the settings in an arbitrary manner via a 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 settings, a user can affect the entire server performance or server presentation to other users.

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:

  • in the xml format
  • since TeamCity 10 in kotlin-based DSL (see a dedicated page). 

    Icon

    Note that when the project is switched to Kotlin, editing of the project settings is disabled in the UI: the Kotlin format is essentially a program, and there is no easy way to propagate UI changes to Kotlin files.

    Since TeamCity 10.0.3, to test kotlin-based settings in a sandbox project, you can download the settings as a zip archive without disabling the UI: on the project settings page, click the Actions menu and select Download settings in kotlin format. A zip archive will be downloaded.

Committing Current Project Settings to VCS

Icon

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.

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 not to accidentally change 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 be checked into the version control.

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

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

11 Comments

  1. If I use versioned settings with git, are the versioned settings always stored in the master branch?

    1. Marc, the settings are stored in the .teamcity folder in the default branch (master, unless otherwise specified).

  2. Suppose I have project settings stored in source control and I create a new branch feature/new-feature. After committing and pushing modifications to source, I want to update a build configuration for the branch without affecting the configuration on the default branch. Can I do this through the UI, or can this only be accomplished by modifying project-config.xml on the branch by hand?

  3. Hi Glen,

    at this time you can change settings only in the default branch from web UI, so the only way to change settings in branch is to edit them by hand.

  4. Hello.

    I work with system integration and as such we have a lot of individual smaller applications that we use Team City to automate build and test processes. I think it's 300+ applications, divided into ca 60 components, each component corresponds to a build configuration on the Team City server. In turn the 60 components/build configurations is divides into two build projects.

    All of thees share at least some code at some point.

    On top of that we usually have 4-7 major branches going at a time (plus some with minor changes), many times with changes spanning all over the code base. This means every new branch generates two new build projects, with all or some of the 60 build configurations.

    I should also mention that each build configuration has on average maybe 10 VCS roots.

    As you can imagine, changes in a branch that requires changes in build projects or build configurations on Team City represents quite a problem for us. We will have to perform the change in every projects, but at different times depending on when a particular branch/trunk is affected by the change.

     

    Now, I would like to use Team City's functionality for synchronizing with VCS (subversion in our case) as a way to let the build configuration settings follow along to a branch.

    What I'm seeing in front of me, is basically just branching, creating an empty project in Team City, pointing it at the new branch - and then see all the different build configurations automatically populated in the new project, from the new branch.

    This would then allow us to merge any change we have made in a specific branch, back to trunk and then on to other branches as we merge any way.

    The problem with this is that each new project in Team City gets a new and unique Id, witch of course messes up my plan the use the SVN-merge feature.

    I had an idea to only store the build configuration settings in subversion. Maybe even together with the source code of the applications it is responsible for building. But it doesn't seem possible.

    Is anything like what I am trying to propose here, at all possible?


    Very thankful for any tip or idea.

    1. So from what I've been reading of the JetBrains implementation of the DSL, you would need to "recreate" all your projects using the DSL, and giving them a unique ID through the DSL would allow you to extend and merge in branches that include new jobs/configurations. They don't suggest changing IDs on existing jobs, so I think you would want to backup your configs using TeamCity 10 to get the Kotlin DSL generated, then edit the DSL in order to change the ID of the jobs to a unique base system based on something like (application>component>branch/build config) and recreate your jobs with new names/descriptions that may include "Generated via DSL, update through OURGITREPO or contact DevOps to get your job/branch added".

  5. How do i revert/rollback project settings in teamcity 9.1.4? provided my settings are version controlled in git

    Thanks,

    Dipesh

    1. You can revert commit in git and push the result to the remote repository, TeamCity should detect it and change configs accordingly.

  6. We store teamcity settings in Git. I have a default branch called 'dev' and feature branches. I have '.teamcity' folder in both the branches, but when i try to make changes in the feature branches, they do not take affect and only when i make changes in the 'dev' branch they take affect. How can make the settings for each branch independent from one another.?

    Thanks

    1. TeamCity server uses settings from the default branch only. But when build starts in a branch and settings root has such a branch and you use 'use settings from VCS mode', then it will take settings from a branch but for this build only.