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

Git support in TeamCity is implemented as a plugin. Git source control with Visual Studio Online is supported.

This page contains description of the Git-specific fields of the VCS root settings.
Common VCS Root properties are described here.


Git needs to be installed on the agents if the agent-side checkout is used.

Important Notes


On this page:


General Settings



Fetch URL

The URL of the remote Git repository used for fetching data from the repository.

Push URL

The URL of the target remote Git repository used for pushing tags to the remote repository. If blank, the fetch URL is used.

Default branch

Set to refs/heads/master by default. This is the default branch, used in addition to the branch specification, or when the branch specification is empty. Note that parameter references are supported here.

Branch specification

Lists the patterns for branch names, required for feature branches support. The matched branches are monitored for changes in addition to the default one. The syntax is similar to checkout rules: +|-:branch_name, where branch_name is specific to the VCS, i.e. refs/heads/ in Git (with the optional * placeholder). Read more. Note that only one asterisk is allowed and each rule has to start with a new line, see the section below.

Use tags as branches

Allows you to use git tags in branch specification (e.g. +|-:refs/tags/<tag_name>). By default, tags are ignored.

Username style

Defines a way TeamCity binds a VCS change to the user. Changing the username style will affect only newly collected changes. Old changes will continue to be stored with the style that was active at the time of collecting changes.


Select whether you want to ignore the submodules, or treat them as a part of the source tree.

Username for tags/merge

A custom username used for labeling.

Branch Matching Rules

  • If the branch matches a line without patterns, the line is used.
  • If the branch matches several lines with patterns, the best matching line is used.
  • If there are several lines with equal matching, the one below takes precedence.

    Everything that is matched by the wildcard will be shown as a branch name in TeamCity interface. For example, +:refs/heads/* will match refs/heads/feature1 branch but in the TeamCity interface you'll see only feature1 as a branch name.
    The short name of the branch is determined as follows:
  • if the line contains no brackets, then full line is used, if there are no patterns or part of line starting with the first pattern-matched character to the last pattern-matched character.
  • if the line contains brackets, then part of the line within brackets is used.
    When branches are specified here, and if your build configuration has a VCS trigger and a change is found in some branch, TeamCity will trigger a build in this branch.

Supported Git Protocols

The following protocols are supported for Git repository URL:

  • ssh: (e.g. ssh://git.somwhere.org/repos/test.git, ssh://git@git.somwhereElse.org/repos/test.git, scp-like syntax: git@git.somwhere.org:repos/test.git)

    Be Careful


    The scp-like syntax requires a colon after the hostname, while the usual ssh url does not. This is a common source of errors.

  • git: (e.g. git://git.kernel.org/pub/scm/git/git.git)
  • http: (e.g. http://git.somewhere.org/projects/test.git)
  • file: (e.g. file:///c:/projects/myproject/.git)

    Be Careful


    When you run TeamCity as a Windows service, it cannot access mapped network drives and repositories located on them.

Authentication Settings

Authentication Method



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.
For the agent-side checkout, it is supported only if git 1.7.3+ client is installed on the agent. See TW-18711.
For Git hosted from Team Foundation Server 2013, specify NTLM credentials here.

Private Key

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

Available Private Key options:

  • Uploaded Key: uses the key(s) uploaded to the project. See SSH Keys Management for details.
  • Default Private key - Uses the mapping specified in <USER_HOME>/.ssh/config if the file exists or the private key file <USER_HOME>/.ssh/id_rsa (the files are required to be present on the server and also on the agent if the agent-side checkout is used).
  • Custom Private Key - Supported only for server-side checkout, see TW-18449. When this method is used, specify an absolute path to the private key in the Private Key Path field. If required, specify the passphrase to access your SSH key in the corresponding field.

For all the available options to connect to GitHub, please see the comment.

Authenticating to Visual Studio Online

When configuring a VCS Root for a project hosted on Visual Studio Online,  enable alternate credentials support in your VSO account.

Enabling Alternate Credentials

Applications that work outside the browser, such as the git client or the command-line TFS client, require basic authentication credentials to work. You can edit the VSO profile to set a secondary username that can be used in this case.

After navigating to your VSO account portal, use the menu at the top-right to edit your profile. The Credentials tab allows enabling alternate credentials. After clicking Enable alternate credentials, set a secondary username and password to use when configuring a VCS Root.

Server Settings

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 core.autocrlf=true in a repository config). When not selected, no line-endings conversion is performed (works as setting core.autocrlf=false). Affects the server-side checkout only. A change to this property causes a clean checkout.

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 .BuildServer/system/caches/git and .BuildServer/system/caches/git/map. The field specifies the mapping between repository url and its directory on the TeamCity server. Leave this field blank to use the default location.

Agent Settings

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 %env.TEAMCITY_GIT_PATH%, the automatically detected git will be used, see Git executable on the agent for details

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.

Use mirrors

Since TeamCity 9.0 When enabled (default), TeamCity clones the repository on each agent and uses the mirror as an alternate repository. As a result, this speeds-up clean checkout (because only the working directory is cleaned), and saves disk space (as there is only one clone of the given git repository on an agent).

Git executable on the agent

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.TEAMCITY_GIT_PATH% value.

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.

If 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:

  • for Windows - it tries to run git.exe at:
    • C:\Program Files\Git\bin
    • C:\Program Files (x86)\Git\bin
    • C:\cygwin\bin
  • for *nix - it tries to run git at:
    • /usr/local/bin
    • /usr/bin
    • /opt/local/bin
    • /opt/bin

If git wasn't 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.


To configure a connection from a TeamCity server running behind a proxy to a remote Git repository, see this section.

Configuring Git Garbage Collection on Server

TeamCity maintains a clone on the server for every Git repository it works with, so the process which collects changes in a large Git repository may cause memory problems on the server.

To ensure good performance while working with Git repositories, Git garbage collection needs to be configured: besides removing unreferenced objects from the repository, git gc also "defragments" some files under .git directory, which decreases memory usage on TeamCity server and increases performance.  There's a feature request for automatic git gc, but at the moment  you need to configure it manually.

To configure Git garbage collection:

  1. Install native git on the server machine.
  2. Define the following internal properties:
    1. teamcity.server.git.executable.path=<path to git executale on the TeamCity server machine>
    2. teamcity.server.git.gc.enabled=true
  3. (Optional) By default, 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.
  4. (Optional) By default, 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 * * ? *
  5. Restart the server for the properties to take effect.

When Git gc is configured, TeamCity will run it automatically in the background 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 run git gc manually after stopping the TeamCity server.


Internal Properties

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. Prior to 8.0.4 the default was 600.



The fetch process idle timeout. The fetch process reports what it is doing in the stdout and is killed if there is no output during this timeout. It is deprecated in favor of teamcity.git.idle.timeout.seconds since TeamCity 8.1, the git-plugin uses it only if its value is greater than the value of teamcity.git.idle.timeout.seconds. Its default value was 600 before 8.1.



Defines whether TeamCity runs git fetch in a separate process



The value of the JVM -Xmx parameter for a separate fetch process



When fetch in a separate process is used, it makes thread-dumps of itself and stores them under TEAMCITY_DATA_DIR/system/caches/git/<git-XXX>/monitoring (directory mapping can be found in TEAMCITY_DATA_DIR/system/caches/git/map). Thread dumps are useful for investigating problems with cloning from remote repository. This parameter specifies how long thread-dumps are to be stored.



Whether TeamCity should run git gc during the server cleanup (native git is used)



The path to the native git executable on the server



Maximum amount of time to run git gc


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



Since 9.0 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, because Git cannot clone a subdirectory of a repository. You can only map the whole repository to a specific directory using the following checkout rule +:.=>subdir. The rest of the checkout rules are not supported.

Known Issues

  • java.lang.OutOfMemoryError while fetch repository. Usually occurs when there are large files in the repository. By default, TeamCity runs fetch in a separate process. To run fetch in the server process, set the teamcity.git.fetch.separate.process internal property to false.
  • Teamcity run as a Windows service cannot access a network mapped drives, so you cannot work with git repositories located on such drives. To make this work, run TeamCity using teamcity-server.bat.
  • inflation using streams in JGit prevents 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 OutOfMemoryError.

Git support is implemented as an open-source plugin. For development links, refer to the plugin's page.

See also:

Administrator's Guide: Branch Remote Run Trigger

  • No labels


  1. Is there a way to prevent TeamCity from cluttering the log with very verbose progress information from git? Presuming that it would help if I could somehow tell TeamCity not to pass the --progress flag to git, but I don't know how to do that.

    1. Hi Marc,

      there is no way to disable that at the moment, sorry. Actually we thought of this as a feature: git clones are sometimes slow, with such a logging you can see what's actually going on and what is an estimate for clone to complete. I wonder why the logging is a problem for you? When one opens a build log, the 'Updating sources' block is collapsed, so you shouldn't see it.

      1. We are also looking for a way to "mute" this noise. The problem is if you are actively examining the logs and expand all leaves in the tree it takes a long time to go past the progress logs of git, and they are typically useless. If there is an error git should still print and report it, and the goal of the CI system is that I do NOT have to watch the console, I just let it run. We also disable the progress output of npm and other tools for this reason, it is "human friendly" output, that doesn't make sense in the logs unless needed explicitly for debugging.

  2. Is there a way to add an option to the git clone command? We don't need the entire repository to be downloaded for our builds, so 

    git clone --depth 1

    would be much faster. Our build agents take an extremely long time to do a clone of the whole danged repository. 

    1. Hi Richard,

      I don't think there is a reason to add such option. TeamCiy 9 uses git alternates and only the first build fetches whole repository, all subsequent builds reuse it.

    2. Hi Richard,

      Since TeamCity 9.0 it is recommended to use Git alternates to speed up checkout. To enable alternates check Use mirrors option in Git VCS root settings.
      For more details please see comments to the related request: https://youtrack.jetbrains.com/issue/TW-39904.

  3. Thanks for the response! We're stuck on TeamCity 8.x due to corporate cheapness. We've spent more money via man hours trying to solve this problem than the cost of the upgrade. 

    1. Do you use the latest 8.x version?

      1. We're using 8.1.5, which I think is the last 8.x release.

        1. You can enable git alternates in TeamCity 8.1.5 by adding the


          parameter either to agent config (it will affect all configurations built on the agent) or to a build configuration (it will affect this configuration on all agents).

        2. You can also make TeamCity to do a clone with the --depth=1 option by adding



          parameters to an agent or a build configuration config, but I think it is more efficient to use alternates.

          1. Cool! I will try that straight away!

          2. teamcity.git.use.shallow.clone=true


            Does this work to give a shallow clone in TeamCity 9.1.1 ?

            If not, would I have to downgrade to 8.x?

            Do I have to turn off alternates ? (teamcity.git.useAlternates=false ?)

            I have "Use Mirrors" unchecked in the VCS settings section.

            Creating a clone without the depth = 1 option is always going to fail in our environment.

            1. Why do you need a shallow clone in 9.1? git alternates are faster and work out-of-box.

  4. We've run into a checkout error with git 2.6.1 on windows (TeamCity 9.1.3). We're using Windows build agents, but Linux server. We're checking out code on the agent, and using mirrors. This all seems to work well, until today. We seem to have a Windows filename too long error:

    Failed to perform checkout on agent: 'd:/TCQuikViewBuildAgent/Git/bin/git reset --hard ae38a51451469dbbb4079a7177deadda155a9f4b' command failed.
    stderr: error: unable to create file quikview-application-Shell/src/test/flexmonkey/testSuites/miniRegressionInitSuite/testCases/_19Contract_ResetRenewal_ContractReset_ResetContractforActiveSubscriber_NotVerified_SubscriberDetails_CARE_IR.as (Filename too long)

    The file name isn't too long. It's the path that's too long. Regardless, this looks like a windows error, and I'm surprised Windows Server 2012 R2 STILL has this issue. The fix could be this: 

    •Many Windows programs (including the Windows Explorer) have problems with directory trees nested so deeply that the absolute path is longer than 260 characters. Therefore, Git for Windows refuses to check out such files by default. You can overrule this default by setting core.longPaths, e.g. git clone -c core.longPaths=true ....

    How can I do this in TeamCity on the agent?

  5. Hi Richard,

    you can puth the following into the user-level or system-level git config on every agent:

    longPaths = true

    You can either do that manually, or you can create a build configuration executing the following command:

    git config --global core.longPaths true

    it assumes that git is in the %PATH%. You can run this build configuration on all agents by selecting "Agent: <All enabled compatible agents>" in run custom build dialog. Hope it helps.

    1. Thanks.
      I tried this at the system level and it worked. 
      We had been using our own, invented, self contained build agents. As such, we can deploy the same agent config to a bunch of different servers with the same settings. The agent is self contained in a single directory. It's a poor man's Puppet install? Docker? Anyhow, it has its drawbacks, and this problem is one of them. Some tools just don't want to be self contained. 
      Thanks again. We're working now.
  6. Hi there, 

    We're running TeamCity from behind the proxy, however our Git repository leaves outside. The git repo provider has just dropped support for SSH and we have to switch to HTTPS. 

    To configure command line git is simple enough: 

    git config --global --add http.https://outside-git-repo-url.proxy http://internal-proxy:8080

    The agent is set to: VCS Checkout Mode: "Automatically on agent", with above git config setting. Nevertheless, running a git checkout in TC doesn't work, and prints out the message: 
    Failed to collect changes, error: List remote refs failed: java.net.ConnectException: Connection timed out outside-git-repo-url

    We can checkout from remote git repo on the agent box without the problems, but TC running checkout through that agent is not able to do it. Any ideas? 

    Thanks, Maciej

  7. I am also having trouble with git commands from TeamCity (running on Windows) behind a proxy and my proxy requires username and password. I am looking at the jgit code and the proxy config should use the environment variables http_proxy and https_proxy. But that is not working. I am on 9.1

    Is this the project you bundle with TeamCity https://github.com/eclipse/jgit ? If so how old is your fork and would it include this commit? https://github.com/eclipse/jgit/commit/c3a073527ea0d6b0f5cbdef10dfd107de0e1c3d8



  8. Hi Nick,

    you can specify http proxy settings as described here: https://youtrack.jetbrains.com/issue/TW-12363#comment=27-153937.

  9. Yes, but not with username and password or https. Or am I missing something reading the link above? it says the "A current workaround for unauthenticated proxy usage"

    1. Nick, hope  this section will be helpful.

      1. Yes thank you for the response, again my proxy requires username and password to access it. I tried those you mention and I tried them like below putting the username and password inline and it does not work.

        I also tried Dhttp.proxyUser and Dhttp.proxyPassword and those do not work either.
        1. Nick, sorry, I'm somehow missed the fact that you need to configure proxy authentication. At this time TeamCity indeed doesn't support proxies which require authentication, the proxyUser and proxyPassword options doesn't seem to be standard (http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html). The only workaround at this moment it to configure proxy to allow no-authentication access from TeamCity server machine.

          1. Understood, thanks for your time and responses Dmitry Neverov and Julia Alexandrova

        2. Nick, sorry we cannot be more helpful at this point. Please vote for the related issue in our tracker.