SFTP/SSH targets

The SFTP/SSH target in Buddy stores the connection to a remote server using SFTP (Secure File Transfer Protocol) or SSH (Secure Shell) and lets every pipeline reuse it for file transfers and remote command execution. Authentication supports inline passwords, inline SSH keys, and keys stored in Buddy Assets, with optional proxy chaining for hosts behind a bastion.

How to add an SFTP/SSH target in Buddy

Navigate to the Targets tab where all globally defined connections are listed.

Image loading...

Click the New target button and select SFTP/SSH from the dropdown menu.

Image loading...

SFTP/SSH connection settings

After selecting the SFTP/SSH option, a configuration form will open with the following fields:

• Name - the target name generates a unique ID for identification, which can be manually edited.
• Scope - specifies which pipelines have access to the target.
• Proxy - optional proxy target used to connect to the server through an intermediary.

Image loading...

Authentication credentials source

The SFTP/SSH target supports three authentication methods, selected in the Authentication credentials source field:

• Inline password - log in with a username and password.
• Inline SSH key - authenticate with a manually entered SSH key.
• SSH key from Assets - select a key from the Assets section in Buddy.

Image loading...

Other connection fields:

• Address & port - server address as a domain name (e.g. sftp.example.com) or IP (e.g. 192.168.1.1). If the server uses the default port, you can omit it.
• Username / Password - server login credentials. A password is required only for username-based authentication. You can also use variables, e.g. ${SFTP_USER} and ${SFTP_PASSWORD}.
• Private SSH key & Passphrase - if using an SSH key, paste the key into the Private SSH key field and the passphrase (if any) into the Passphrase field.

Image loading...

• Target path - default directory path on the server where operations run. Variables like ${TARGET_PATH} are supported.
• Tags - labels used to group and match targets.

Proxy target

The SFTP/SSH target supports a proxy, used to reach a server through an intermediary (typical bastion / jump host setup).

Click the + icon and select one of the options:

• New SFTP/SSH target - create the proxy as a separate SFTP/SSH target.
• New inline proxy - configure the proxy directly inside the current target.

Image loading...

A proxy can be configured with the same authentication methods as standard SFTP/SSH targets. A target configured as a PROXY is itself a fully functional SFTP/SSH target, so you can use it as both an intermediary and as a regular target for SSH commands or file transfers directly to the proxy server.

After configuring and saving the proxy, it is assigned to the current SFTP/SSH target and shown in the Proxy section of the form. It can be edited or removed at any time.

Image loading...

Once the required fields are filled in and the proxy is tested, click Add this target to save the settings.

Testing the SFTP/SSH connection

Before saving, use Test connection to verify the credentials and network access. The test connects from a Buddy runner to the host and port you provided and authenticates with the chosen method. If the test fails, see Troubleshooting below.

Using the SFTP/SSH target in YAML pipelines

Reference the target by ID in any SSH or file transfer action:

yaml
- pipeline: "Deploy via SFTP"
  trigger_mode: ON_EVERY_PUSH
  actions:
    - action: "Upload build"
      type: "FTP"
      target: "sftp-prod"
      local_path: "dist/"
      remote_path: "/var/www/app"
    - action: "Restart service"
      type: "SSH_COMMAND"
      target: "sftp-prod"
      commands:
        - "systemctl restart app"

You can also define the target inline:

yaml
- action: "Run remote script"
  type: "SSH_COMMAND"
  targets:
    - target: "sftp-prod"
      type: "SSH"
      host: "sftp.example.com"
      port: 22
      auth:
        username: "$SFTP_USER"
        password: "$SFTP_PASSWORD"
  commands:
    - "ls -al /var/www/app"

See the SSH command, Transfer, and Download YAML references for the full field list.

Troubleshooting SFTP/SSH connection errors

• Permission denied (publickey) - the SSH key is not authorized on the server. Append the public key to ~/.ssh/authorized_keys on the target host for the configured user. Check file permissions: ~/.ssh must be 700, authorized_keys must be 600.
• Permission denied (password) - either the password is wrong or PasswordAuthentication no is set in sshd_config. Switch the server to allow passwords or switch the target to key-based auth.
• Connection timeout / host unreachable - the server is not exposed to Buddy runners. Whitelist the Buddy IP addresses on your firewall, or route the connection through a proxy target.
• Host key verification failed - the host key has changed (e.g. after a server rebuild). Buddy retries connections with the new key automatically; if the issue persists, re-test the connection from the target form.
• Bad passphrase / key decrypt failed - the passphrase does not match the encrypted private key. Re-paste the key and passphrase carefully; trailing newlines in the key field can also break decryption.
• No such file or directory - the Target path does not exist on the server. Create it first or remove the path from the target so the action's own path takes over.

See also

• FTP/FTPS target
• SSH command action - YAML reference
• Transfer action - YAML reference
• Download action - YAML reference
• Targets - REST API
• Custom variables in pipelines