Skip to main content

SSH Runner

The SSH Runner executes commands on a remote machine over Secure Shell (SSH). It enables secure remote automation for deployments, infrastructure management, and post-build operations.

When to Use​

Use the SSH Runner when you need to:

  • Deploy artifacts to remote servers or environments.
  • Execute administrative or operational commands on remote machines.
  • Perform infrastructure management or maintenance tasks.
  • Run post-build validation or cleanup steps remotely.

Parameters​

ParameterDescription

Step Name

Optional step name. Defaults to the runner name if not specified.

Working Directory

Directory where the commands will be executed.

Host

The SSH host address of the remote machine.

Port

The SSH port number. Defaults to 22.

User

The SSH user name used to establish the connection.

Authentication Type

The method used to authenticate with the remote machine. Supported options include:

  • Password: Authenticates using the SSH user’s password. This option is simple to configure but is generally less secure than key-based authentication. This option includes:

    • Password: The password used for authentication.

  • Default SSH Key: Uses the default SSH private key available on the BuildNinja agent machine (~/.ssh/id_rsa) to authenticate with the remote host. This option includes:

    • Root Password: The password of the remote machine’s root user, used to authorize access if required.
    • Passphrase: The passphrase associated with the default SSH private key, if the key is encrypted.

  • Custom SSH Key: Uses a user-provided SSH private key for authentication. This is useful when a specific key is required for access or when different keys are needed for different environments. This option includes:

    • Root Password: The password of the remote machine’s root user, used when privileged access is required.
    • SSH Key: The custom SSH private key used to authenticate with the remote host.
    • Passphrase: The passphrase associated with the provided SSH private key, if the key is encrypted.
note

The corresponding public key must be added to the remote machine’s ~/.ssh/authorized_keys file.

Commands

The commands to execute on the remote machine, entered one per line.

Typical Use Cases​

Common scenarios for using the SSH Runner include:

  • Copying build artifacts to staging or production servers.
  • Restarting or managing services remotely.
  • Running database migrations or maintenance scripts.
  • Executing commands on cloud virtual machines or remote environments.

Example​

This example demonstrates how to deploy build artifacts to a remote server.

Scenario
Deploy build artifacts to a production server.

Configuration settings:

  • Step Name: Deploy Application

  • Host: prod.server.com

  • Port: 22

  • User: deploy

  • Authentication Type: SSH Key

  • Commands:

    sudo systemctl stop app
    cp /tmp/build/* /opt/app/
    sudo systemctl start app

Limitations​

  • Network latency or connectivity issues can affect build reliability.
  • Security risks exist if credentials or keys are mismanaged.
  • Remote environments may differ from agent environments, leading to inconsistencies.
  • Debugging failures on remote systems can be more complex.

Best Practices​

  • Prefer key-based authentication over password-based access.
  • Restrict SSH permissions using least-privilege principles.
  • Log all executed commands for auditing and troubleshooting.
  • Avoid long-running or interactive remote tasks.