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 plugin; with the Visual Studio Add-in, 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.
Native Git for VCS-related operations on the server
TeamCity can now use native Git for VCS-related operations on the server. Using native Git improves the performance of the checking for changes operations on the server in comparison with the previously used JGit implementation. It also fixes a number of issues related to large Git repositories.
See known issues of the current native Git implementation in TeamCity.
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 |
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: |
Use tags as branches | Allows monitoring / checking out git tags as branches making branch specification match tag names as well as branches (for example, |
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 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: (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 / personal access token | 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. You can use a personal access token instead of a password to authenticate in GitHub, Azure DevOps Services, GitLab, JetBrains Space, and Bitbucket. When connecting to Azure DevOps, remember to set the Code access scope to Code (read) / Code (read and write) for versioned settings in the repositories you are about to access from TeamCity. When using an existing Bitbucket Cloud, Bitbucket Server, GitLab or Azure DevOps Services connection to create a VCS Root, TeamCity will use a refreshable token instead of the password. |
Refreshable token | If a VCS root that fetches data from a GitHub, GitHub App, Bitbucket Server, Bitbucket Cloud, Azure DevOps, GitLab, or JetBrains Space was configured using a TeamCity connection, refreshable tokens are enabled by default. Such tokens are short-lived providing more security than passwords or personal access tokens: the TeamCity server refreshes them automatically without sharing any related data with agents. The Token field displays information about the user who obtained the token and the connection that provided the token. You can specify a username here if there is no username in the clone URL (the username specified here overrides the username from the URL). For Azure DevOps, GitHub App, Bitbucket Server, Bitbucket Cloud, JetBrains Space and GitLab connections you can click the Acquire new button to instantly reissue the token used by the VCS root with a token issued for the current user. ![]() |
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).
|
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, see the available options here.
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 |
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 |
Checkout policy | This setting defines how TeamCity performs a checkout to a build agent.
|
Clean Policy/Clean Files Policy | Specify here when the 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 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 exploit.
Agent-side checkout rules limitations
The Git plugin uses git sparse-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:
Note that rules must not remap files. That is, the following rule is not supported: +:dirA/dirA1 => dirA/dirA2
.
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 ([prefix/]
). Only the rules +:dirA => [prefix/]dirA
are supported for agent-side checkout, and the [prefix/]
must be the same for all rules.
For example:
Note that the following rule is not supported: +:dirA=>[prefix/]dirA/postfix
. If you append [/postfix]
to the checkout directory path and the configuration's VCS checkout mode is set to "Always checkout files on agent", new builds will be unable to start.
![Checkout directory path error Checkout directory path error](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-postfixCheckoutError.png)