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

The VCS Checkout mode is a setting that affects how project sources reach an agent. This mode affects only sources checkout. The current revision and changes data retrieving logic is executed by the TeamCity server and thus TeamCity server needs to access the VCS server in any mode.

Depending on the version control used, agents can require command line clients installed and available in PATH on the agents (e.g. Perforce, Git, Mercurial).

The checkout mode is configured on the build configuration's Version Control Settings page, in the Checkout Options section (an advanced setting).

TeamCity has three different VCS checkout modes:

Checkout mode


Automatically on server

This is the default setting. The TeamCity server will export the sources and pass them to an agent before each build. Since the sources are exported rather than checked out, no administrative data is stored in the agent's file system and version control operations (like check-in, label or update) cannot be performed from the agent. TeamCity optimizes communications with the VCS servers by caching the sources and retrieving from the VCS server only the necessary changes. Unless clean checkout is performed, the server sends to the agent incremental patches to update only the files changed since the last build on the agent in the given checkout directory.


  • The server side checkout simplifies administration overhead. Using this checkout mode, you need to install VCS client software on the server only (applicable to Perforce, Mercurial, TFS, Clearcase, VSS). Network access to VCS repository can also be opened to the server only. Thus, if you want to control who has access to the source repositories, the server side checkout is usually more effective.
  • In some cases this checkout mode can lower the load produced on VCS repositories, especially if Clean Checkout is performed often, due to the caching of clean patches by the server.
  • Note that in the server checkout mode the administration directories (like .svn, CVS) are not created on the agent.

Automatically on agent

The build agent will check out the sources before the build. This checkout mode is supported only for CVS, Subversion, TFS, Mercurial, Perforce, ClearCase and Git. Agent-side checkout frees more server resources and provides the ability to access version control-specific directories (.svn, CVS, .git); that is, the build script can perform VCS operations (e.g. check-ins into the version control) — in this case ensure the build script uses credentials necessary for the check-in.


  • Agent checkout is usually more effective with regard to data transfers and VCS server communications. The agent side checkout creates necessary administration directories (like .svn, CVS), and thus allows you to communicate with the repository from the build: commit changes and so on.
  • Machine-specific settings (like configuring SSL communications, etc.) have to be configured on each machine using agent-side checkout.
  • "Exclude" VCS Checkout Rules in most cases cannot improve agent checkout performance because an agent checks out the entire top-level directory included into a build, then deletes the files that were excluded. Perforce and TFS are exceptions to the rule, because before performing checkout, specific client mapping(Perforce)/workspace(TFS) is created based on checkout rules. "Exclude" checkout rules are not supported for Git and Mercurial when using checkout on an agent due to these DVCS limitations.
  • Integration with certain version controls can provide additional options when agent-side checkout is used. For example, Subversion.

Do not check out files automatically

TeamCity will not check out any sources automatically, the default build checkout directory will still be created so that you could use it to check out the sources via a build script. Please note that TeamCity will accurately report changes only if the checkout is performed on the revision specified by the build.vcs.number.* properties passed into the build. 

(warning) The build checkout directory will not be cleaned automatically, unless the directory expiration period is configured.  


See also:

Administrator's Guide: VCS Checkout Rules





















  1. Could someone specify the root directory where TeamCity server checks out to?

  2. Is there a way to have Git-based agent-side checkouts work from a clone maintained on each agent? We can't use server-side checkout because your Java implementation doesn't understand soft links, and it seems it would be more efficient for each agent to maintain a naked repository locally - particularly given how many git submodules we're using but currently have to checkout in full every time. 20 minutes to check out is... painful.

    1. Hi Tim,

      actually git plugin does exactly that. Only the first agent-side checkout should be slow, all subsequent do incremental update and should be fast.

    2. Sorry, missed the fact you use submodules, they are indeed might be re-cloned, please watch/vote for https://youtrack.jetbrains.com/issue/TW-15492

      1. Hi, thanks for the reference. I'm going to try to cobble something together for us to use in the meantime, and I'll try to make it generic enough to be a workaround for others - hopefully you've passed enough information down in the build parameters.