TeamCity
 
You are viewing the documentation for an earlier version of TeamCity.

Git

Last modified: 20 April 2023

TeamCity supports Git out of the box. Git source control with Visual Studio Team Services is supported (see authentication notes below).

This page contains description of the Git-specific fields of the VCS root settings. For common VCS Root properties, see this section.

General Settings



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

    note

    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)

    note

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

Authentication Settings



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

Authenticating to Visual Studio Team Services



If you use Git source control with Visual Studio Team Services, the following options are available to you:

Server Settings



These are the settings used in case of the server-side checkout.

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.

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

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 the large Git repository may cause memory problems on the TeamCity server without periodical Git garbage collection. TeamCity can automatically run git gc periodically when path to native Git client is configured on the server.

Since version 2017.1.3 TeamCity runs Git garbage collection automatically, 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:

  1. Install a native Git client manually on the TeamCity server.

  2. Specify the directory to the Git executable:

    1. either add it to the %Path%/ $PATH environment variable and restart the server

    2. or set it in the teamcity . server . git . executable . path internal property without the server restart.

To configure Git garbage collection prior to TeamCity 2017.1.3, in addition to the steps above, do the following:

  1. Define the teamcity.server.git.gc.enabled=true internal property

  2. (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.

  3. (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 * * ? *

  4. Restart the server for the properties to take effect.

Git LFS



Starting with 10.0 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. More information on Git LFS can be found in Git LFS documentation.

Internal Properties



For Git VCS it is possible to configure the following internal properties:

Agent configuration for Git:

limitations Limitations



When using checkout on an agent, a limited subset of checkout rules is supported. Since TeamCity 10.0, 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 +:some/dir=>some/otherDir.

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 increase memory available to this process, change teamcity.git.fetch.process.max.memory internal property (see description of this property above).

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

Development Links



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