TeamCity 8.0 Help

Git (JetBrains)

Git support in TeamCity is implemented as a plugin.

This page contains description of the Git-specific fields of the VCS root settings. Common VCS Root properties Configuring VCS Roots.

General Settings

Option

Description

Fetch URL

The URL of the remote Git repository.

Push URL

The URL of the target remote Git repository.

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

In this area list all the branches you want to be 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). Working with Feature Branches. Note that only one asterisk is allowed and each rule has to start with a new line, see the branchMatchingRules.

Use tags as branches

Allows you to use git tags in branch specification. 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.

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 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 Protocols for Server Side Checkout

The following protocols are supported for the server-side VCS Checkout Mode:

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

Password

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 VCS Checkout Mode, it is supported only if git 1.7.3+ client is installed on the agent. See TW-18711.

Private Key

Valid only for SSH protocol. A private key must be in 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 VCS Checkout Mode is used).

  • Custom Private Key - Supported only for VCS Checkout Mode, 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.

Server Settings

These are the settings used in case of the server-side VCS Checkout Mode.

Option

Description

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 VCS Checkout Mode. 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 VCS Checkout Mode, 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 %\env.TEAMCITY_GIT_PATH%, the automatically detected git will be used, see agentGitPath 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.

Git executable on the agent

The path to the git executable can be configured in the agent properties by setting the value of the TEAMCITY_GIT_PATH environment variable.

If the path to git is not configured, the git-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 - try to run git.exe at:

    • C:\Program Files\Git\bin

    • C:\Program Files (x86)\Git\bin

    • C:\cygwin\bin

  • for *nix - try to run git at:

    • /usr/local/bin

    • /usr/bin

    • /opt/local/bin

    • /opt/bin

If git wasn't found in any of these locations, try to run the git accessible from the $PATH.

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.

Internal Properties

For Git VCS it is possible to configure the following Configuring TeamCity Server Startup 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.idle.timeout.seconds since 8.1-EAP3, 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-EAP3.

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

teamcity.server.git.gc.enabled

false

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

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 git gc

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

Build 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.use.local.mirrors

false

When checkout on agent: whether TeamCity should clone to the local agent a mirror first and then clone to the working directory from this local mirror. This option speed-ups clean checkout, because only the build working directory is cleaned. Also if a single root is used in several build configurations, cloning will be faster.

teamcity.git.useAlternates

false

Alternates work like mirrors, but instead of cloning from a mirror to a working directory TeamCity uses a mirror as an alternate repository . As a result there is only one clone of the given git repository on an agent. This property can be set either in the agent properties or as a parameter in the build configuration.

teamcity.git.use.shallow.clone

false

When checkout on agent: run fetch with the option '--depth=1' if the agent uses local mirrors. This property can be set either in the agent properties or as a parameter in the build configuration.

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

  • Tagging is not supported over the HTTP protocol

  • 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 Configuring TeamCity Server Startup Properties 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 Git.

Last modified: 20 April 2023