TeamCity Cloud 2023.03 Help

SSH Keys Management

You can upload private SSH keys into TeamCity projects. Uploaded keys can be used when configuring VCS roots, and in the SSH Agent build feature.

Supported Key Format

TeamCity supports keys in the PEM and OpenSSH formats. Keys that use different formats need to be converted. For example, you can use the PuTTY Key Generator to convert unsupported Putty private keys (*.ppk) to the PEM format. To do this, navigate to the Conversions | Export OpenSSH key menu.

Upload SSH Keys to TeamCity Server

To allow TeamCity projects to access remote repositories via SSH keys, you first need to upload your keys to these projects.

  1. In Project Settings, click SSH Keys.

  2. On the SSH Keys page, click Upload SSH Key.

  3. In the "Upload SSH Key" dialog, browse for a private key file and specify a name for this key.

  4. Click Save to save the uploaded key.

Add SSH Keys to TeamCity

Uploaded SSH keys are stored in the <TeamCity Data Directory>/config/projects/<project>/pluginData/ssh_keys directory. TeamCity tracks this directory so uploaded keys become available in the current project and its subprojects without the need to restart a server.

Configure VCS Root Settings

Once required SSH keys are uploaded, modify the VCS Root settings to select a key that your project should use.

  1. Go to the Project Settings | VCS Roots page and click the required root.

  2. In the Authentication Settings section, click the required "Private Key" option:

    • Uploaded Key — select this option to utilize the key(s) uploaded to the project.

    • Default Private Key — select this option to utilize 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. Fill the Private Key Path field with an absolute path to the private key file on the server machine. If the key is encrypted, specify the passphrase in the corresponding field.

Select an SSH key


TeamCity REST API allows external applications and scripts to access TeamCity resources via URLs. You can utilize this feature to upload SSH keys and customize VCS Root settings.

View Uploaded Keys

GET <server_URL>/app/rest/projects/<project_locator>/sshKeys

Upload New SSH Keys to TeamCity Server

POST <server_URL>/app/rest/projects/<project_locator>/sshKeys?fileName=<Key_Name>
  • Body: the contents of the private key file

  • Content-Type header: "text/plain"

Set up VCS Authentication Settings

  • Switch the "Authentication method" to "Uploaded Key". Request body: "TEAMCITY_SSH_KEY".

    PUT <server_URL>/app/rest/vcs-roots/<locator>/properties/authMethod
  • Select a particular SSH key. Request body: SSH key name.

    PUT <server_URL>/app/rest/vcs-roots/<locator>/properties/teamcitySshKey
  • Specify a passphrase required by password-encrypted SSH keys. Request body: plain password string.

    PUT <server_URL>/app/rest/vcs-roots/<locator>/properties/secure:passphrase

Distribute SSH Keys to Build Agents

If you configure the agent-side checkout, the server passes SSH keys to agents. During a build, the Git plugin downloads the key from the server to the agent, and removes this key after git fetch/clone is complete.

To transfer the key from the server to the agent, TeamCity encrypts it with a DES symmetric cipher. For a more secure way, configure an HTTPS connection between agents and the server.

In addition to VCS roots, uploaded SSH keys can be used in SSH Agent build features. See this link for more information: SSH Agent.

Last modified: 14 March 2023