SSH Keys Management

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.

To allow TeamCity projects to access remote repositories via SSH URLs, you first need to upload your private 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.

You can also upload private keys when creating new projects from repository URLs. If you use an SSH URL, TeamCity switches the Authentication mode to "SSH Keys" and shows a list of the previously uploaded private keys. If you did not upload a required key before, click Upload SSH key and point TeamCity to the required file.

Uploaded SSH keys are stored in the following directory:

• <TeamCity Data Directory>/config/projects/<project>/pluginData/ssh_keys

If a key was uploaded from the "Create Project" page, TeamCity assigns it to the parent project of the created project. In this case, uploaded keys are saved to the following directory:

• <TeamCity Data Directory>/config/projects/<Parent_Project_ID>/pluginData/ssh_keys

note

Keep the access to the TeamCity Data Directory secure, as a server stores SSH keys in an unmodified/unencrypted form on the file system.

If you use GitHub Deploy Keys or similar authentication workflows, you can let TeamCity generate SSH keys instead of generating them manually. This approach is more secure (since generated keys are not stored on your local machine) and significantly faster. The latter is especially helpful if you re-generate and rotate SSH keys every once in a while.

1. In Project Settings, click SSH Keys.

2. Click the Generate SSH Key button.

   

3. Enter the key name, select the key type, and click Generate.

4. If you need a private or a public key for your new generated key:

   • A private key is stored in the <TeamCity Data Directory>/config/projects/<parent project>/pluginData/ssh_keys directory.

   • A public key is accessible from the main SSH Keys page (click the Copy the public key link under a required key). Paste this key to your version control service (for example, in GitHub: "Repository settings | Deploy Keys | Add deploy key").

5. Select the generated key in the Authentication Settings of your TeamCity VCS root. For your convenience, keys generated in TeamCity are placed in a separate category.

   

tip

Watch our video tutorial on how to check out from SSH repositories with SSH keys.

Private SSH keys are employed only when your VCS root is configured to work with a remote repository via an SSH URL (for instance, git@github.com:...). If you create a project using an SSH URL and choose/upload a private key from the "Create Project" page, TeamCity automatically sets up required settings, and you do not need to modify a Configuring VCS Roots.

Otherwise, if you want to update a project that authenticates to a VCS via a token or a password so that it starts using an SSH key instead, you will need to manually update a corresponding Configuring VCS Roots.

1. Navigate to Administration | <Your_Project> | VCS Roots and click Edit next to the required root.

2. Update the Fetch URL and/or Push URL fields to use an SSH URL instead. For example, change https://github.com/username/repository_name.git to git@github.com:username/repository_name.git.

3. Scroll down to Authentication Settings and choose one of the Private Key options.

   

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

4. Click Test Connection at the bottom of the page to check you current values, and Apply to save and exit the root settings.

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.

note

Keys are removed from agents for security reasons. For example, the tests executed by the build can leave some malicious code that will access the build agent file system and acquire the key. However, tests cannot get the key directly since it is removed by the time they are running. It makes it harder but not impossible to steal the key. Therefore, the agent must also be secure.

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.

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.

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

POST
/app/rest/projects/<project_locator>/sshKeys?fileName=<Key_Name>

POST
/app/rest/projects/<project_locator>/sshKeys/generated?keyName=NewKey&keyType=RSA

DELETE
/app/rest/projects/<project_locator>/sshKeys?fileName=<Key_Name>