SSH Exec

The SSH Exec enables TeamCity to execute arbitrary remote commands using SSH.

The settings common for all runners are described here. This article details the SSH Exec runner settings.

The fields below support parameter references: any text between percentage signs (%) is considered a reference to a property by TeamCity. To prevent TeamCity from treating the text in the percentage signs as reference to a property, use two percentage signs to escape them: for example, if you want to pass %Y%m%d%H%M%S into the build, change it to %%Y%%m%%d%%H%%M%%S.

Option	Description
Step name	Optional Name of the build step displayed in the TeamCity UI.
Step ID	ID for this build step, which must be unique across all steps of this configuration. Used in URLs, REST API, DSL, HTTP requests to the server, and configuration settings in the TeamCity Data Directory.
Execute step	Enables you to modify the default build condition, and optionally add more build conditions.
Deployment Target
Target	SSH server hostname or IP address.
Port	Optional Port. Defaults to port 22.
Use pty	Optional Specify the type of the pseudoterminal (pty). For example, `vt100`. If empty, pty is not allocated (default).
Deployment Credentials
Authentication method	Select an authentication method: Uploaded Key — uses the key(s) uploaded to the project. See SSH Keys Management for details. Default Private Key — performs private key authentication using the `~/.ssh/config` settings or, if no settings file exists, using the `~/.ssh/id_rsa` private key file. Custom Private Key — performs private key authentication using the specified private key file and passphrase. Password — uses simple password authentication. SSH-Agent — uses SSH agent for authentication, where the SSH-Agent build feature must be enabled. The current secure connection implementation accepts any certificate provided by the remote host. No trust checks are performed!
SSH Commands
Commands	Specify a new-line delimited set of commands to execute in the remote shell. The remote shell is started in the home directory of an authenticated user. The shell output will be available in the TeamCity build log. SSH Exec runs the shell in non-interactive mode, which imposes corresponding restrictions. Tip for Linux users To use bash aliases in this runner, add the following shell options to your script: shopt -s expand_aliases source /home/user/.bash_profile

Example

For example, consider how to create a build step that builds static content for a web site. After uploading the static content to the web server, you need to execute a deploy.sh script to refresh the site. Suppose you use the jdoe account on the SSH server with the home directory /jdoe, and the SSH server is configured to use SSH keys for authentication.

Follow the steps in Generated SSH Keys to generate a new SSH key pair in your project. Call the key pair WebServerKey.
Copy the public key from the WebServerKey key pair.
Log in to the jdoe account on your SSH server and follow the instructions from your SSH server provider to add the WebServerKey public key to this account.
In your project's build configuration, go to the Build Steps page and click Add build step.
On the New Build Step page, select the SSH Exec runner.
On the New Build Step: SSH Exec page, fill in the fields, as follows:
- Step name — Enter RunDeployScript
- Target — Enter ssh.example.com
- Authentication method — Select Uploaded key
- Username — Enter jdoe (the username for the account on the SSH server)
- Select key — Select WebServerKey from the dropdown list
- Commands — Enter the following shell commands:
  echo 'running deploy.sh ...' /home/jdoe/scripts/deploy.sh
Click Save to create the build step.

Last modified: 18 September 2024