Git
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.
General Settings
Option | Description |
---|---|
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. |
Set to | |
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: |
Use tags as branches | Allows you to use git tags in branch specification (e.g. |
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. |
Submodules | 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 matchrefs/heads/feature1
branch but in the TeamCity interface you'll see onlyfeature1
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)
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)
Authentication Settings
Authentication Method | Description |
---|---|
Anonymous | 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:
|
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.
true
Server Settings
These are the settings used in case of the server-side checkout.
Option | Description |
---|---|
Convert line-endings of all text files to CRLF (works as setting | |
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 |
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.
Option | Description |
---|---|
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. |
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.
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:
Install native git on the server machine.
Define the following internal properties:
teamcity.server.git.executable.path=<path to git executale on the TeamCity server machine>
teamcity.server.git.gc.enabled=true
(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.(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 * * ? *
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.
Internal Properties
For Git VCS it is possible to configure the following internal properties:
Property | Default | Description |
---|---|---|
teamcity.git.idle.timeout.seconds | 1800 | 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. |
teamcity.git.fetch.timeout | 1800 | 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.fetch.separate.process | true | Defines whether TeamCity runs git fetch in a separate process |
teamcity.git.fetch.process.max.memory | 512M | The value of the JVM -Xmx parameter for a separate fetch process |
teamcity.git.monitoring.expiration.timeout.hours | 24 | When fetch in a separate process is used, it makes thread-dumps of itself and stores them under |
teamcity.server.git.gc.enabled | false | Whether TeamCity should run |
teamcity.server.git.executable.path | git | The path to the native git executable on the server |
teamcity.server.git.gc.quota.minutes | 60 | Maximum amount of time to run |
teamcity.git.cleanupCron | 0 0 2 * * ? * | Cron expression for the time of a cleanup in git-plugin, by default - daily at 2a.m. |
teamcity.git.stream.file.threshold.mb | 128 | 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 |
teamcity.git.buildPatchInSeparateProcess | true | 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. |
teamcity.git.mirror.expiration.timeout.days | 7 | 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. |
teamcity.git.commit.debug.info | false | Defines whether to log additional debug info on each found commit |
teamcity.git.sshProxyType | 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. | |
teamcity.git.sshProxyHost | Ssh proxy host | |
teamcity.git.sshProxyPort | Ssh proxy port | |
teamcity.git.connectionRetryAttempts | 3 | Number of attempts to establish connection to the remote host for testing connection and getting a current repository state before admitting a failure |
teamcity.git.connectionRetryIntervalSeconds | 2 | Interval in seconds between connection attempts |
Agent configuration for Git:
Property | Default | Description | |
---|---|---|---|
teamcity.git.use.native.ssh | false | When checkout on agent: whether TeamCity should use native SSH implementation. | |
teamcity.git.idle.timeout.seconds | 1800 | 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. |
Limitations
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 tofalse
.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 increaseteamcity.git.stream.file.threshold.mb
. Additionally, it is recommended to increase the overall amount of memory dedicated for TeamCity to preventOutOfMemoryError
.
Development Links
Git support is implemented as an open-source plugin. For development links, refer to the plugin's page.