TeamCity Git checkout does not populate the Git credential cache (credential.helper=cache)

Symptoms

On a TeamCity build agent, the Git VCS uses HTTPS authentication and the agent has the Git credential cache helper configured:

[credential]
    helper = cache --timeout=3600

After a TeamCity source checkout, ~/.git-credential-cache/socket is not populated. A later build step that relied on the cached credential (for example, a Maven SCM plugin that pushes a tag) then fails, because no password is cached.

A manual git clone on the same agent, entering the username and password interactively, does create ~/.git-credential-cache/socket. Only the TeamCity checkout leaves the cache unpopulated.

This commonly appears after migrating agents to a newer OS and Git version (for example, RHEL 7.9 with Git 1.8.3 to RHEL 9.8 with Git 2.52), where the cache was previously populated and now is not.

Cause

TeamCity does not seed the Git credential cache during checkout, by design. Agent-side Git operations run with the credential helpers reset and a temporary TeamCity helper supplied for the single operation:

git -c credential.helper= -c credential.helper=<teamcity-temporary-helper> <command>

The empty -c credential.helper= clears any inherited system, global, or user helper (including cache). The temporary TeamCity helper provides the VCS root credentials to that one Git command and does not store them to any downstream helper, so the checkout authenticates but never writes to credential.helper=cache. This isolates the VCS root credentials from the agent environment.

The difference across Git versions comes from Git's handling of the empty credential.helper= reset. Reliable clearing of the helper list via an empty value arrived around Git 2.9. On Git 1.8.3 the reset does not fully take effect, so a configured cache helper stays active alongside TeamCity's and is populated after checkout. On Git 2.9 and later (including Git 2.52) the reset works as intended, only TeamCity's non-storing helper runs, and the cache stays empty. Relying on the checkout to seed the cache was never a guaranteed behavior.

Resolution

Give the dependent build step its own credentials instead of relying on the checkout to seed the credential cache.

Recommended: VCS Labeling build feature

Move the tagging into TeamCity with the VCS Labeling build feature. It creates and pushes tags using the VCS root's own credentials, so it does not depend on the Git credential cache.

1. In the build configuration, add a VCS Labeling build feature and point it at the relevant VCS root.
2. Set the tag/label pattern.
3. Optionally limit labeling to successful builds only.
4. Remove or adjust the build step (for example, the Maven SCM tagging) so it no longer authenticates against Git itself.

When the fetch URL is read-only, set a Push URL on the Git VCS root. See Git for the VCS root settings.

Alternative: provide credentials to the build step

Store a password or personal access token as a TeamCity secure (password) parameter and reference it in the build step (for a Maven SCM plugin, in the SCM connection URL, or as -Dusername= / -Dpassword=), or use an SSH key. The secure parameter is masked in the build log.

Short-term workaround: keep using the credential cache

The internal parameter teamcity.git.provideCredentialHelper=false makes TeamCity authenticate the checkout through the askpass mechanism only, instead of overriding the credential helper. A configured credential.helper=cache then stays active during checkout, and Git populates ~/.git-credential-cache after authenticating.

This parameter is internal and undocumented, and its behavior may change in future TeamCity releases. Use it only as a short-term workaround, not a long-term solution. Set it as a build-configuration parameter or in the agent buildAgent.properties file; it has no effect when set as a server-wide internal property.