Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

tocThe Version Control Settings page for a build configuration allows configuring how project source code is retrieved from VCS: you can attach a VCS Root here and configure checkout options.

Anchor
VCSCheckoutMode
VCSCheckoutMode

...

Checkout mode

Description

Anchor
preferAgentCheckout
preferAgentCheckout
Prefer to checkout files on agent

Since TeamCity 10.0, this is the default setting for the newly created build configurations. When upgrading, the checkout mode settings for existing build configurations are preserved.

With this setting enabled, TeamCity will use the agent-side checkout described below if possible. If the agent-side checkout is not possible, TeamCity will display a corresponding health report item and will use the server-side checkout described below.

TeamCity falls back to the server-side checkout in the following cases:

  • No Git or Mercurial client is found on on the agent
  • The Git or Mercurial client is present on the agent, but is of the wrong version
  • The agent has no access to the repository
  • If a Perforce client cannot be found on the agent using the same rules as while performing actual checkout or if stream depot is used and the checkout rules are complex (other than . => A )

Anchor
ServerCheckout
ServerCheckout
Always checkout files on server

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.

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

Anchor
AgentCheckout
AgentCheckout
Always checkout files on agent

The build agent will check out the sources before the build. 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.

VCS client software has to be installed on the agent (applicable to Perforce, Mercurial, Git) 

Note
titleNotes
  • 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.
    There is a known issue with CVS VCS root ignoring exclude checkout rules when using checkout on an agent.
  • Integration with certain version controls can provide additional options when agent-side checkout is used. For example, Subversion.

Anchor
Do not check out files automatically
Do not check out files automatically
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.

 

Additional checkout and display settings

Since TeamCity 2017.1, the Display settings section of the VCS Root checkout options for a build configuration is renamed into Changes calculation settings.

Here you can configure whether:

  • TeamCity will show changes from snapshot dependencies 
  • to exclude the default  branch changes from other branches
    • TeamCity will run builds in the default branch and show it in the UI, which is the default behavior. If this is undesirable, you can uncheck this box and the default branch will not be shown in the UI. This can be useful if you want to build pull requests only.

Note that unchecking the option will affect all the aspects concerning the default branch, including:

  • build chains: if a chain is triggered in a branch, and this branch does not exist in one of the configurations that is a part of the chain, previously TeamCity fell back on the default branch. If the default branch in this configuration is not allowed, building the dependency will fail
  • the behavior of the Run dialog: the run custom build dialog will be displayed asking to select a branch
  • triggers and notifications.

...























See also:

Panel
bgColor#FFFFFF
borderStyledashed

Administrator's Guide: VCS Checkout Rules