This page contains description of the Git-specific fields of the VCS root settings.
For common VCS Root properties, see this section.
Git command line client needs to be installed on the agents if the agent-side checkout is used.
On this page:
The URL of the remote Git repository used for fetching data from the repository.
The URL of the target remote Git repository used for pushing annotated tags created via VCS labeling build feature to the remote repository. If blank, the fetch URL is used.
Configures default branch. Parameter references are supported here. Default value is
Lists the patterns for branch names, required for feature branches support. The matched branches are monitored for changes in addition to the default branch. The syntax is similar to checkout rules:
Use tags as branches
Allows monitoring / checking out git tags as branches making branch specification match tag names as well as branches (e.g.
Defines a way TeamCity reports username for a VCS change. The username is reported based on the Author field of the Git commit and can include name, email or their combinations.
Select whether you want to ignore the submodules, or treat them as a part of the source tree. Submodule repositories should either not require authentication or use the same protocol and accept the same authentication as configured in the VCS root.
Username for tags/merge
A custom username used for labeling.
refs/heads/feature1branch, but in the TeamCity interface you'll see only
feature1as a branch name.
The following protocols are supported for Git repository URL:
ssh: (e.g. ssh://git.somwhere.org/repos/test.git, ssh://firstname.lastname@example.orgElse.org/repos/test.git, scp-like syntax: email@example.com:repos/test.git)
The scp-like syntax requires a colon after the hostname, while the usual ssh url does not. This is a common source of errors.
file: (e.g. file:///c:/projects/myproject/.git)
When you run TeamCity as a Windows service, it cannot access mapped network drives and repositories located on them.
Select this option to clone a repository with anonymous read access.
Specify a valid username (if there is no username in the clone URL; the username specified here overrides the username from the URL) and a password to be used to clone the repository.
Valid only for SSH protocol. A private key must be in the OpenSSH format. Select one of the options from the Private Key list and specify a valid username (if there is no username in the clone URL; the username specified here overrides the username from the URL).
For all the available options to connect to GitHub, please see the comment.
Authenticating to Visual Studio Team Services Applications that work outside the browser, such as the git client or the command-line TFS client, require basic authentication credentials to work. When configuring a VCS Root for a project hosted on Visual Studio Team Services, enable alternate credentials support in your Visual Studio Team Services account.
If you use Git source control with Visual Studio Team Services, the following options are available to you:
These are the settings used in case of the server-side checkout.
Convert line-endings to CRLF
Convert line-endings of all text files to CRLF (works as setting
Custom clone directory on server
To interact with the remote git repository, the its bare clone is created on the TeamCity server machine. By default, the cloned repository is placed under
These are the settings used in case of the agent-side checkout.
Note that the agent-side checkout has limited support for SSH. The only supported authentication methods are "Default Private Key" and "Uploaded Private Key" .
If you plan to use the agent-side checkout, you need to have Git 1.6.4+ installed on the agents.
Path to git
Provide the path to a git executable to be used on the agent. When set to
Clean Policy/Clean Files Policy
Specify here when the "git clean" command is to run on the agent, and which files are to be removed.
When enabled (default), TeamCity clones the repository under the agent's
To configure a connection from a TeamCity server running behind a proxy to a remote Git repository, see this section.
TeamCity needs Git command line client version 1.6.4+ on the agent in order to use the agent-side checkout.
The recommended approach is to ensure that the git client is available in PATH of the TeamCity agent and leave the "Path to git" setting in the VCS root blank.
If you only have the git command line on some machines, set "Path to git" setting in the VCS root to the %env.
Instead of adding Git to the agent's PATH, you can set the TEAMCITY_GIT_PATH environment variable (or
env.TEAMCITY_GIT_PATH property in the agent's buildAgent.properties file) to the full path to the git executable.
TEAMCITY_GIT_PATH is not defined, the Git agent plugin tries to detect the installed git on the launch of the agent. It first tries to run git from the following locations:
If git is not found in any of these locations, it tries to run the git accessible via the
PATH environment variable.
If a compatible git (1.6.4+) is found, it is reported in the
TEAMCITY_GIT_PATH environment variable. This variable can be used in the Path to git field in the VCS root settings. As a result, the configuration with such a VCS root will run only on the agents where git was detected or specified in the agent properties.
TeamCity server maintains a clone for every Git repository it works with, so the process which collects changes in the large Git repository may cause memory problems on the TeamCity server if the Git garbage collection for the repository was not run for a long time.
TeamCity can automatically run git gc periodically when native Git client can be found on the server.
When TeamCity runs Git garbage collection, the details are logged into the teamcity-cleanup.log. If git garbage collection fails, a corresponding warning is displayed. To fix the warning / meet automatic git gc requirements, perform the following:
Pathenvironment variable and restart the server,
teamcity.server.git.executable.pathinternal property without the server restart.
TeamCity executes Git garbage collection until the total time doesn't exceed 60 minutes quota; the quota can be changed using the
teamcity.server.git.gc.quota.minutes internal property.
Git garbage collection is executed every night at 2 a.m., this can be changed by specifying the internal property with a cron expression like this:
"teamcity.git.cleanupCron=0 0 2 * * ?" (restart the server for the property to take effect)
If git gc process is slow and cannot be finished within allotted time, check git-repack configuration in the default git configuration files. e.g. "--window-memory" can be increased to improve git gc performance.
When Git gc is configured, TeamCity will run automatically in the background it for all currently monitored VCS roots. With large Git repositories, if git gc has not been performed for a long time, garbage collection may take significant time. Alternatively, you can stop TeamCity and delete the entire content of <TeamCity Data Directory>/system/caches/git directory to force fresh clones. If you do not want to do a fresh clone, you can stop TeamCity and run "git gc" manually for all the <git-XXX> git clones in the directory.
TeamCity supports Git LFS for agent-side checkout. To use it, install git 1.8.5+ and Git LFS on the build agent machine. Git LFS should be enabled using the 'git lfs install' command (on Windows an elevated command prompt may be needed). More information is available in Git LFS documentation.
For Git VCS it is possible to configure the following internal properties:
The idle timeout for communication with the remote repository. If no data were sent or received during this timeout, the plugin throws a timeout error to prevent hanging of the process forever.
(deprecated) Override of "teamcity.git.idle.timeout.seconds" for git fetch operation
Defines whether TeamCity runs git fetch in a separate process
The value of the JVM -Xmx parameter for a separate fetch process. You also need to ensure the server machine has enough memory as the memory configured will be used in addition to the main server process and there can be several child processes doing git fetch and each using the configured amount of the memory.
Whether TeamCity should run
The path to the native git executable on the server
Maximum amount of time to run
0 0 2 * * ? *
Cron expression for the time of a cleanup in git-plugin, by default - daily at 2a.m.
Threshold in megabytes after which JGit uses streams to inflate objects. Increase it if you have large binary files in the repository and see symptoms described in TW-14947
Git-plugin builds patches in a separate process, set it to false to build patch in the server process. To build patch git-plugin has to read repository files into memory. To not run out of memory git-plugin reads only objects of size smaller than the threshold, for larger objects streams are used and they can be slow (TW-14947). With patch building in a separate process all objects are read into memory. Patch process uses the memory settings of the separate fetch process.
The number of days after which an unused clone of the repository will be removed from the server machine. The repository is considered unused if there were no TeamCity operations on this repository, like checking for changes or getting the current version. These operations are quite frequent, so 7 days is a reasonably high value.
Defines whether to log additional debug info on each found commit
Type of ssh proxy, supported values: http, socks4, socks5. Please keep in mind that socks4 proxy cannot resolve remote host names, so if you get an UnknownHostException, either switch to socks5 or add an entry for your git server into the hosts file on the TeamCity server machine.
Ssh proxy host
Ssh proxy port
Number of attempts to establish connection to the remote host for testing connection and getting a current repository state before admitting a failure
Interval in seconds between connection attempts
Agent configuration for Git:
When checkout on agent: whether TeamCity should use native SSH implementation.
The idle timeout for the git fetch operation when the agent-side checkout is used. The fetch is terminated if there is no output from the fetch process during this time. Prior to 8.0.4 the default was 600.
When using checkout on an agent, a limited subset of checkout rules is supported. Git-plugin translates some of the checkout rules to the sparse checkout patterns. Only the rules which do not remap files are supported:
An unsupported rule example is
OutOfMemoryError, but can be time-consuming (see the related thread at jgit-dev for details and the TW-14947 issue related to the problem). If you meet conditions similar to those described in the issue, try to increase
teamcity.git.stream.file.threshold.mb. Additionally, it is recommended to increase the overall amount of memory dedicated for TeamCity to prevent
Git support is implemented as an open-source plugin. For development links, refer to the plugin's page.
Administrator's Guide: Branch Remote Run Trigger