SSH Run Script Action

The SSH Run Script action is a premium action which used to run scripts on an SSH server. The action can either run an entire script or a list of commands. All output is written to the build log as it is received from the host.

SSH Run Script

Name

A friendly name for this action (will be displayed in the actions workflow area).

Enabled

Determines if this action will be run within the relevant stage.

Host Name

The URL or IPv4 address of the SSH host to connect to. The host should be accessible from all agents able to run the build containing this action. If any connection issues are detected they will appear in the build log. Action will connect and represent itself as an xterm client. In addition it will use a channel to send commands so that it can easily detect when they have been completed. If a script is

used in the action, SFTP will be used to upload the script to the host for execution. This guarantees that the script runs in the context of the host, and does not have to deal with any translation issues between the actions client and the server. Once run the script file will be removed from the SSH host.

Port

The port number that the SSH host will be listening on. Port 22 is the default port for SSH hosts.

Run Type

Select whether you want to specify a sequence of Commands or a Script File to run.

Script

This text area is shown when the Commands option is selected for the Run Type. Enter a list of commands to run one after the other on the target host. When run, the action will open a channel once connected and proceed to call each command in sequence waiting for the previous command to complete. Once all commands have been run, the channel and connection will be closed and the action will completed, returning the exit code of the last run command.

Note: For each subsequent command to be run, the terminal must return to a shell prompt. It is suggested that this method is used only when running simple commands.

Script File

This input box is shown when the Script file option is selected for the Run Type. Enter the path to the script file.

When the action is run, the script file is uploaded to the SSH host using SFTP and placed in the base directory of the logged in user. The script is then updated to be executable and executed under the users account. This requires the user to be able to write and execute files in their base directory. The action will then wait for the script to complete before setting the Exit Code Variable to the last error code of the script, and then closing the channel and connection.

Convert any Windows newlines (CLRF) in script file to UNIX newlines (LF)

This is shown when the Script file option is selected for the Run Type. If this is ticked, any Windows newlines (CLRF) in script file are converted to UNIX newlines (LF).

Clean up script after run

If this is ticked, the script file will be removed after run is cleaned up.

Authentication

Username

The username under which all the commands will be run. The user will only be logged in for the lifetime of the action.

Password

The password for the supplied user. This password is stored as an encrypted value within the action and once entered cannot be read by those editing the action. It will also not appear in any logs.

Private File Key

If the host uses SSH keys, the file containing the key can be supplied here. The action supports several private key formats: PKCS #8, OpenSSH/OpenSSL and PuTTY .ppk.

PKCS #8 keys

RFC 5208 (PKCS #8)

Encrypted Example:

Unencrypted Example:

PuTTY .ppk keys

PuTTY

Example:

PuTTY-User-Key-File-2: ssh-rsaEncryption: noneComment: ssh-rsa-key-20170905Public-Lines: 2AAAAB3NzaC1yc2EAAAADAQABAAAAQQCqoReRwOoMuikYoIOY8giCZ5KdMYwdk1/MeJqLMd/yu5CZvFeH3moJjgscLn8HHcc2RZsTtdRbSgYks7Ast4ezPrivate-Lines: 4AAAAQFFrx5x0qvrhxoSK6+EK9caMd+js4MioL5mZn112sj/YO3ZB0iwPHWwvEqhJ+8L+mnK3kNxqpBMim+//1AF14gEAAAAhAMhSO1oJMMkVpKNQTNecvn6skbInmDRMD9Q/xJXlpTEBAAAAIQDaDiR163FkcqJ/9VzcVHBhVrqE9qnQcL/a2yMmJzJEswAAACEAmTru7evQBk5IwaReq1Lcojagkw7wkLCbo9LUw6X3Vpk=Private-MAC: e4378e86478e8f1cdd2fb1bbb634965104a8808c

OpenSSH/OpenSSL (SSLeay) keys

OpenSSH and OpenSSL

Example:

Passphrase

If the private key was encrypted with a passphrase it should be placed in this field. The passphrase is encrypted when stored in the database, and will not appear in any logs.

Options

Use UTF8 Encoding

If this is ticked, UTF8 encoding is used when communicating with the SSH server.

Character Encoding Name

Visible only if 'Use UTF8 Encoding' is not ticked.

Enter the international standard name for the encoding of the response from your SSH server. See Encoding for full list. Leave blank to use the current code page on the agent operating system.

Fail on non-zero exit code

If this is ticked, a non-zero exit code causes the action to fail.

Ignore Exit Codes

The list of exit codes to ignore (comma-delimited).

Exit Code Variable

Select a build variable to store the last exit code received from the script or commands that were run. All commands are run through an SSH channel. After running all the commands supplied, the channel returns its exit status.

Expression variables which cannot be modified are not listed.

Continue running next command on failure

Visible only if 'Command' Run Type is selected under the 'SS Run Script' tab.

If this is ticked, the next command continues to run on failure.

Script timeout

The time in milliseconds to wait before the action should timeout when waiting for a response from the host.

Ignore warnings

If this is ticked, any warnings logged will not mark the action with a warning status.