TeamCity
 
7.0
You are viewing the documentation for an earlier version of TeamCity.
  1. TeamCity Documentation
  2. Administrator's Guide
  3. Managing Projects and Build Configurations
  4. Creating and Editing Build Configurations
  5. Configuring VCS Settings
  6. Configuring VCS Roots
  7. Git (JetBrains)

Git (JetBrains)

Last modified: 20 April 2023

This page contains description of the fields and options available when setting up VCS roots using the Git Version Control System. The VCS is visible as "Git (JetBrains)" in VCS chooser to eliminate confusion with third-party plugin if third-party plugin is installed and as "Git" otherwise.

tip

  • Remote run is supported in IntelliJ IDEA and Eclipse plugins, pre-tested commit is not yet supported in any of the IDE plugins.

  • Initial Git checkout may take significant time (sometimes hours), depending on the size of your project history, because the whole project history is downloaded during the initial checkout.

General Settings



Option

Description

Fetch URL

The URL of the remote Git repository.

Push URL

The URL of the target remote Git repository.

Ref name

The name of the git ref (e.g. "master", "refs/tags/v5.1"), or left this field blank to use "master" branch.

Clone repository to

The path to a directory on TeamCity server where a bare repository should be created. Leave it blank to use default path.

User Name Style

Changing user name 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

Custom username used for labeling

tip

Starting with TeamCity 7.1 you can configure the branches you want to monitor in a build configurations right in the VCS root:

Branch Specification

In this area list all the branches you want to be monitored for changes. The syntax is similar to checkout rules: +|-:branch_name, where branch_name is specific to the VCS e.g. refs/heads/ in Git (with optional * placeholder). Note that only one asterisk is allowed, and each rule has to start with a new line.

  • 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 TeamCity interface you'll see feature1 only as a branch name. The short name of the branch is determined as:

  • 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 VCS trigger and a change is found in some branch, TeamCity will trigger a build in this branch.

Branch Name

Use this field to define a so-called default branch. Default branch is used in situations when branch name was not specified. For example, if someone clicks on a Run button TeamCity will create build in default branch. Note that parameter references are allowed in branch specification as well.

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)

    note

    Scp-like syntax requires a colon after hostname, while 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 a mapped network drives and repositories located on them.

Authentication Settings



Authentication Method

Description

Anonymous

Select this option to clone a repository with anonymous read access.

Default Private Key

Valid only for SSH protocol and applicable to both fetch and push urls. Uses mapping specified in <USER_HOME>\.ssh\config if that file exists. The key should be present on the server and also on the agent if agent-side checkout is used. Specify a valid username if there is no username in the clone URL. The username specified here overrides username from the URL.

Password

Specify username and password to be used to clone the repository. (Until TeamCity 7.1.2 this is supported only for server-side checkout, since TeamCity 7.1.2 it is supported also for agent-side checkout if git 1.7.3+ client is installed on the agent. See TW-18711.)

Private Key

Valid only for SSH protocol and applicable to both fetch and push urls. (Supported only for server-side checkout, see TW-18449). When this method is used you have to specify an absolute path to private key in Private Key Path field. A private key must be in OpenSSH format.

Server Settings



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 performed (works as setting core.autocrlf=false). Affects a server-side checkout only. A change to this property causes a clean checkout. Introduced in TeamCity 7.1.2.

Agent Settings



Please note that agent-side checkout has limited support for SSH. The only supported authentication method is "Default Private Key". Also you should set "StrictHostKeyChecking" to "no" in <USER_HOME>\.ssh\config, or add keys of remote hosts to the Known-Hosts database manually. If you plan to use VCS Checkout Mode, you need to have Git 1.6.4+ installed on the agents.

Option

Description

Path to git

Provide path to a git executable to be used on agent. When set to %\env.TEAMCITY_GIT_PATH% - will use automatically detected git, see agentGitPath for details

Clean Policy/Clean Files Policy

Specify here when "git clean" command is run on agent, and which files should be removed.

Git executable on the agent



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

If path to git is not configured, git-plugin tries to detect installed git on the start of the agent. It first tries to run git at 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 at any of these locations, try to run git accessible from the $PATH.

If compatible git (1.6.4+) is found - it is reported in the TEAMCITY_GIT_PATH environment variable. This variable can be used in Path to git field in VCS root settings. As a result, configuration with such a VCS root will run only on agents where git was detected or specified in 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

600

Idle timeout for communication with remote repository. If no data were sent or received during this timeout - plugin throws a timeout error

teamcity.git.fetch.timeout

600

Fetch process idle timeout. Fetch process reports what it is doing in the stdout and is killed if there is no output during this timeout.

teamcity.git.fetch.separate.process

true

Should TeamCity run git fetch in a separate process

teamcity.git.fetch.process.max.memory

512M

Value of JVM -Xmx parameter for separate fetch process

teamcity.server.git.gc.enabled

false

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

teamcity.server.git.executable.path

git

Path to native git executable on the server

teamcity.server.git.gc.quota.minutes

60

Maximum amount of time to run git gc

teamcity.git.stream.file.threshold.mb

128

Threshold in megabytes after which JGit uses streams to inflate objects. Increase it if you have big binary files in the repository and see symptoms described in TW-14947

teamcity.git.mirror.expiration.timeout.days

7

Number of days after which unused clone of repository will be removed from the server machine. Repository considered unused, if there were no TeamCity operations on this repository, like checking for changes or getting current version. These operations are quite frequent, so 7 days is reasonable high value.

teamcity.git.commit.debug.info

false

Log additional debug info on each found commit

teamcity.git.includeTagsInCurrentState

false

Include tags in the set of branches reported by git-plugin

teamcity.git.sshProxyType

Type of ssh proxy, supported values: http, socks4, socks5 (since 7.1.5)

teamcity.git.sshProxyHost

Ssh proxy host (since 7.1.5)

teamcity.git.sshProxyPort

Ssh proxy port (since 7.1.5)

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 local agent mirror first and then clone to working directory from this local mirror. This option speed-ups clean checkout, because only build working directory is cleaned. Also if single root is used in several build configurations clone will be faster.

teamcity.git.use.shallow.clone

false

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

Limitations



  • When using checkout on agent, limited subset of checkout rules is supported, because Git cannot clone a subdirectory of repository. You can only map whole repository to a specific directory using following checkout rule +:.=>subdir. The rest checkout rules are not supported.

Known Issues



  • Tagging is not supported over HTTP protocol

  • java.lang.OutOfMemoryError while fetch repository. Usually happens when there are big files in repository. By default TeamCity runs fetch in a separate process, to run fetch in the server process set Configuring TeamCity Server Startup Properties teamcity.git.fetch.separate.process to false.

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

  • checkout on agent using ssh protocol can be slow due to java SSH implementation (see TW-14598 for details). To use native SSH implementation set teamcity.git.use.native.ssh to true.

  • inflation using streams in JGit prevents OutOfMemoryError but can be time consuming (see related thread at jgit-dev for details and TW-14947 issue related to the problem). If you meet conditions similar to described in the issue - try to increase teamcity.git.stream.file.threshold.mb. Additionally it is recommended to increase 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 Git.