Git

TeamCity supports Git out of the box. Git source control with Azure DevOps 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.

Important notes:

Remote Run and Pre-Tested Commit are supported in the IntelliJ IDEA and Eclipse plugins; with the Visual Studio Addin use the Branch Remote Run Trigger.
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 used for fetching data from the repository.
Push URL	The URL of the target remote Git repository used for pushing annotated tags created via VCS labeling build feature to the remote repository. If blank, the fetch URL is used.
Default branch	Configures default branch. Parameter references are supported here. Default value is `refs/heads/master`. You can configure Git-plugin to fetch all heads by adding a build configuration parameter `teamcity.git.fetchAllHeads=true`.
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 branch. 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). Here, the pipe* symbol `\|` represents the OR command, as in regular expressions: use `+` for including, OR `-` for excluding.
Use tags as branches	Allows monitoring / checking out git tags as branches making branch specification match tag names as well as branches (for example, `+\|-:refs/tags/<tag_name>` ). By default, tags are ignored.
Username style	Defines a way TeamCity reports username for a VCS change. 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. Submodule repositories should either not require authentication or use the same protocol and accept the same authentication as configured in the VCS root.
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 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: (for example, 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: (for example, git://git.kernel.org/pub/scm/git/git.git)
HTTP: (for example, http://git.somewhere.org/projects/test.git)
file: (for example, 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 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. You can use a personal access token instead of a password to authenticate in GitHub, Azure DevOps Services, GitLab, and Bitbucket. Note that TeamCity does not support token authentication to hosted Azure DevOps Server (formerly, Team Foundation Server) installations. Beginning August 13, 2021, GitHub will no longer accept passwords when authenticating Git operations on GitHub.com. We highly recommend that you use an access token or SSH key instead of password when configuring a VCS root for a GitHub.com repository.
Private Key	Valid only for SSH protocol. A private key must be in the OpenSSH format. Recent versions of OpenSSH no longer generate keys in PEM format by default. The new OpenSSH format is not yet supported by TeamCity (see TW-53615 ). Use the following command to generate TeamCity-compatible keys: `ssh-keygen -t rsa -m PEM`. 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 keys available on the file system in the default locations used by common ssh tools: 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. When this method is used, fill the Private Key Path field with an absolute path to the private key file on the server machine. If required, specify the passphrase to access your SSH key in the corresponding field.

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

You can use a personal access token instead of a password to authenticate in GitHub, Azure DevOps Services, GitLab, and Bitbucket.
Note that TeamCity does not support token authentication to hosted Azure DevOps Server (formerly, Team Foundation Server) installations.

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 keys available on the file system in the default locations used by common ssh tools: 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. When this method is used, fill the Private Key Path field with an absolute path to the private key file on the server machine. If required, specify the passphrase to access your SSH key in the corresponding field.

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

Authenticating to Azure DevOps Services

If you use Git source control with Azure DevOps Services, the following options are available to you:

Personal Access Tokens

To use access tokens, you need to create a personal access token in your Azure DevOps account, where you have to set some Code access scope in your repositories and use it when configuring a VCS root.

Option	Description
Username	Leave blank for TFVC, any value for Git, for example, username
Password	Enter your personal access token created earlier

Required Access Scope

TFS subsystem	Scopes
TFVC	All scopes
Git	Code (read) / Code (read and write) for versioned settings
Work Items	Work items (read)
Commit Status	Code (status)

Alternate Authentication Credentials

To use the login/password pair authentication, you have to enable alternate credentials in your Azure DevOps account, where you can 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.

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.

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.

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 `%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. If a build configuration depends on multiple VCS roots, we suggest that you configure separate agent checkout directories for each of these roots, using VCS checkout rules. This way, `git clean` will never delete these checkout directories during cleaning.
Use mirrors	It is recommended to always leave this option enabled. When enabled (default), TeamCity clones the Git repository and creates its mirror under the agent's `system\git` directory. TeamCity uses this mirror as an alternate repository when updating the checkout directory for a build. This speeds up clean checkout (because only the build working directory is cleaned) and saves disk space (as the mirror is the only clone of the given Git repository on an agent). If you disable this option, TeamCity will clone the repository directly under the build's working directory.

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

If a build configuration depends on multiple VCS roots, we suggest that you configure separate agent checkout directories for each of these roots, using VCS checkout rules. This way, git clean will never delete these checkout directories during cleaning.

Use mirrors

It is recommended to always leave this option enabled.

When enabled (default), TeamCity clones the Git repository and creates its mirror under the agent's system\git directory. TeamCity uses this mirror as an alternate repository when updating the checkout directory for a build. This speeds up clean checkout (because only the build working directory is cleaned) and saves disk space (as the mirror is the only clone of the given Git repository on an agent).

If you disable this option, TeamCity will clone the repository directly under the build's working directory.

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.

Git LFS

TeamCity supports Git LFS for agent-side checkout. To use it, install git 1.8.+ and Git LFS on the build agent machine. Git LFS should be enabled using the git lfs install command (on Windows, an elevated command prompt may be needed). More information is available in the Git LFS documentation.

For LFS, you need to use the same credentials as used for the Git VCS root itself.

We recommend using Git LFS version 2.12.1 or later as earlier versions come with a vulnerability.

Limitations

The Git plugin uses git sparce-checkout to check out Git files on an agent. The plugin is able to perform only simple file mapping operations which limits the set of supported VCS checkout rules for Git.

The following rules are supported:

+:dirA/dirA1
-:dirA/dirA1/dirA2

+:. => dirA/dirA1/dirA2

+:dirA => dirA

+:dirA/dirA1 => dirA/dirA1

+:dirA/dirB/dirC => dirD/dirE/dirA/dirB/dirC

If you specify multiple checkout rules for one root, make sure their checkout directories (the right part of the rule) have a common parent directory. For example:

+:dirA/dirB/dirC => dirG/dirH/dirA/dirB/dirC
+:dirD/dirE/dirF => dirG/dirH/dirD/dirE/dirF

Development Links

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

Last modified: 05 May 2021