You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

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

On this page:

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.


 If your project settings contain passwords, after enabling settings synchronization the passwords will be stored in the VCS in scrambled form; however, anyone with a developer role in the project will be able to see these passwords using the changes difference viewer.

  • if the Show settings changes in builds option is enabled, any user who can see the content of the build's file changes in the TeamCity web UI (having the "View VCS file content" permission) can see all the project settings, including the values of the password fields (in scrambled form)
  • if the projects or build configurations with settings in VCS have password fields defined, the values appear in the XML settings committed into the VCS (though, in scrambled form)
  • 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.   

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

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

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


  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.

    1. As a result of this limitation, we have abandoned our attempts to deploy this feature at our company because it is too much of a nuisance and too risky to edit build settings for branches by hand. Is JetBrains planning to implement support for editing branch build settings through the web UI, and if so, when?

      1. Glen, I'm curious why you want to edit changes in a non-default branch via the web UI. Is this for a testing server that you want to have look similar to production with slightly different settings, or some other reason?

        1. When developing enhancements on a feature branch, it may require new configuration to build in TeamCity, such as a new build step or new agent requirements. Naturally, it is important to test such changes by running a build on the branch before pulling the changes into master; we don't want build configuration changes for one branch to affect builds of other branches until the corresponding source code changes are pulled in.

          1. Good to know, I'm curious whether the new TeamCity 10 feature of "Job DSL" will let you accomplish what you want with less hassle, though I do think the "all or nothing" style of TeamCity configurations via DSL can be a challenge when trying to convert existing jobs.

            1. Hi,

              In fact what Glen described is very serious limitation of your product making it very unfriendly in big projects. For example, I am working on Apache Ignite, out CI contains more than 80 builds for different features across multiple release branches. Now consider the following cases:

              1) We add another module and create suite for it. It is green in new branches with the module, but constantly red in old branches where this module doesn't exist.

              2) I moved tests from config A to config B in Java test suites and want to remove A as it is no longer needed. But if I do so, I will lost test for previous releases and tags, because they still have tests for A. Of course you may say that I can cherry-pick changes to previous release branches, but it is inconvenient and time consuming.

              As a result TC becomes virtually unmanageable in big projects with lots of modules and lots of release branches. Having different configs for different branches will solve this problem. You should really consider implementing it.


              1. Hi Vladimir,

                thanks for suggestion, please watch/vote for https://youtrack.jetbrains.com/issue/TW-44866. As mentioned above you can have different settings in different branches, but there is no UI for that. Consider using Kotlin DSL, it makes settings editing easier.

                1. Dmitry, 

                  Thanks, voted. UI support for multiple branches will add great value to your product.

  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. TeamCity 10 is bringing in a DSL that will allow you to define jobs programmatically, if they are all as similar as you say, this should make your life much easier than messing around in version control to tweak the TeamCity settings.

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



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

  6. Is it possible to add a commit message when we make a change to the teamcity settings? In our case we need to relate it to a JIRA, but I could see plenty of cases where I'd like to document why I'm setting a setting a certain way. (By the way the functionality is fantastic - it's a really great feature)

  7. Hi i agree with Glen. When i saw the headline of this feature i thought it was going to be really helpful for my team. Unfortunately the fact that all the config is stored in a central place is a real chore. Ideally i would like the config for a branch to be stored in that branch. This way you simply point teamcity to a branch and it could pick up the build config. Also if you changed the config it should show up as history in that branch so my developers can easily work out if a failed build is due to a code change or a config change. This also means you could develop your build process in a branch and easily use standard merge features to integrate this back. I think teamcity is a fantastic product and this decision to put the config centrally doesn't seem to conform with the higher quality product i am used to from jetbrains. Hope this is constructive and let me know if you plan to adjust this feature


    1. Hi Ashley,

      thanks for feedback. It is possible to make TeamCity to store settings for different projects in different branches. You can create 2 VCS roots pointing to the different branches of the same repository and use them in corresponding projects to store settings.

      I'm not sure it will be convenient though: projects from different branches exist on the same server, but one will have to switch branches in order to examine neighbour project settings. For example, it won't be possible to search for usages of some parameter across all projects.

      Also standard merge practicies most likely won't work due to structure of xml configs: all projects are stored in directories with name = project externalId and all projects have different external ids, so it would be hard to merge Project_v1/project-config.xml into Project_v2/project-config.xml.

      We are thinking about improvements in this area, but there are no specific plans yet.

      1. Hi, Dmitry,

        One of the benefits for us when we switched from SVN to Git was only needing one VCS root per repository. What you are suggesting would introduce an intolerable nuisance of having to create a new VCS root every time we create a branch - which we do frequently (dozens of times a day company-wide) now that we're on Git.

        Another benefit of storing TeamCity configurations in Git is we could add watches to configurations of shared builds so that we get notifications when they change. Thus we hope that plans are coming soon to fix this feature so that configurations of branches can be edited separately through the UI.

        1. Short-lived branches are already supported in 9.1.x: if you select the 'use project settings from VCS' option and store settings together with sources, then build in branch will use settings from this branch. So it is possible to create a branch, refactor build scripts and TeamCity settings together, run a build in a branch to verify everything is fine, and then merge such branch into default, to apply changes for all builds. There a few limitations to this approach, they are described above

          1. Sorry, I forgot that the real issue for us is the lack of UI support for separate branch configurations; I've updated my previous comment accordingly.

      2. Hi Dmitry

        Thanks for the quick reply. its great to hear you can store different project settings in different branches.The main issue for us is that a single build configuration has a fixed path and has to be stored with other build configurations for that project. I suppose one way round this would be to have a whole new instance of teamcity for each branch of my code but this seems overkill. When you consider plans for any changes in this area i would suggest the possibility of a build-config.xml that can be configured on a per build basis and be retrived from a location in SVN. Otherwise in the meantime would you have any suggestions on if this behaviour is possible to simulate in an Extension and i would consider trying to write this myself.

        1. Creating a new TeamCity instance for each branch is an overkill of course. But it doesn't seem to be necessary, different branches can be handled using project hierarchy. E.g. you can create a top level project named after a product and sub-projects named after a branches (e.g. 'Trunk', 'v1', etc). The 'Trunk' project settings can be stored in the 'trunk' branch. Once you reach the next version, e.g. v10, you can create a 'v10' branch, copy the 'Trunk' project to 'v10' project and configure it to store settings in the 'v10' branch. Creating branches for individual build configuration seems to be too granular.