Configuring VCS Settings

VCS Settings Overview

A Version Control System (VCS) is a system for tracking the revisions of the project source files. It is also known as SCM (source code management) or a revision control system. The following VCSs are supported by TeamCity out-of-the-box: Git, Subversion, Mercurial, Perforce, Team Foundation Server, CVS , StarTeam, ClearCase, SourceGear Vault, Visual SourceSafe.

Connection to a version control system is defined by a TeamCity VCS root. A project or a build configuration in TeamCity can have one or more VCS roots attached; a build configuration and also defines other checkout options like Checkout Rules - these define the workspace for the build.

TeamCity always monitors the repositories from the server-side to detect changes and display them in the UI. Depending on the specified VCS Checkout Mode the actual repository checkout can also happen on the agent-side.

TeamCity performs VCS-related operations per each VCS root separately, thus it is advised to reuse VCS roots with same settings.

When parameter references are used in a VCS root, TeamCity performs VCS-related operations per each "VCS root instance", where "instance" is a unique set of VCS root parameters after references resolution. Adding parameters to the VCS roots does not reduce the number of VCS operations performed, it just allows sharing settings more effectively.

Attach VCS Root

VCS settings are configured on the Version Control Settings page for a project or a build configuration: you can attach an existing VCS root to your project/build configuration, or create a new one to be attached. This is the main part of VCS parameters setup; a VCS Root is a description of a version control system where project sources are located. Learn more about VCS Roots and configuration details here.

Configure Checkout Rules

When several VCS roots are attached or you need to checkout only a portion of the repository, specify the checkout rules for the VCS root to provide advanced possibilities to control sources checkout. With the rules you can exclude and/or map paths to a different location on the Build Agent during checkout.

Configuring Checkout Options for Build Configuration

Checkout Settings

Setting	Description
VCS Сheckout Mode	To define how project sources reach an agent, use the VCS Checkout Mode options.
Сheckout Directory	The Build Checkout Directory is a directory on the TeamCity agent machine where all of the sources of all builds are checked out into.
Clean build	Define whether you want to clean all files in the checkout directory before the build. See Clean Checkout for details.

Changes Calculation Settings

This section, formerly called the Display settings, was renamed into Changes calculation settings since TeamCity 2017.1.

Setting	Description
Show changes from snapshot dependencies	Configure whether TeamCity will show changes from snapshot dependencies. This also affects treatment of pending changes in schedule trigger.
Exclude default branch changes from other branches (since TeamCity 2017.1)	By default, when displaying pending changes in a feature branch, TeamCity includes changes in the default branch as well. This allows tracking the cases when a commit that broke a build was fixed in the default branch, but not in a feature branch. However, for large projects with multiple teams simultaneously working on lots of different branches this means that all the project committers (regardless of the branch they are committing to) will be notified when, for example, a commit in the default branch broke the build or if a force push was performed. If you want to see the changes in a feature branch only, check the box to exclude changes in the default branch from being displayed in other branches.

Setting

Description

Show changes from snapshot dependencies

Configure whether TeamCity will show changes from snapshot dependencies. This also affects treatment of pending changes in schedule trigger.

Exclude default branch changes from other branches (since TeamCity 2017.1)

By default, when displaying pending changes in a feature branch, TeamCity includes changes in the default branch as well. This allows tracking the cases when a commit that broke a build was fixed in the default branch, but not in a feature branch.

However, for large projects with multiple teams simultaneously working on lots of different branches this means that all the project committers (regardless of the branch they are committing to) will be notified when, for example, a commit in the default branch broke the build or if a force push was performed.

If you want to see the changes in a feature branch only, check the box to exclude changes in the default branch from being displayed in other branches.

Disable Building in Default Branch

By default, TeamCity will run builds in the default branch: the Default Branch Settings section, available since TeamCity 2017.1, has the option Allow builds in the default branch enabled.

If this behavior 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.

Configure VCS trigger if you want the build to be started on new changes detection.
Additionally, you can add a label into the version control system for the sources used for a particular build by means of VCS Labeling build feature.

Last modified: 20 April 2023