Publish Over SSH Plugin for Jenkins
This plugins shares many configuration options with two similar plugins:
- Publish over CIFS
- Publish over FTP Please read Publish Over first to learn about their common configuration options. Only options specific to Publish over SSH are documented below.
Features
- SCP - Send files over SSH (SFTP)
- Execute commands on a remote server (can be disabled for a server configuration, or for the whole plugin)
- Use username and password (keyboard-interactive) or public key authentication
- Passwords/passphrases are encrypted in the configuration files and in the UI
- SSH SFTP/ SSH Exec can be used as a build step during the build process (Freestyle and Matrix projects)
- SSH before a (maven) project build, or to run after a build whether the build was successful or not (see Build wrappers below)
- The plugin is "promotion aware" (send files directly from the artifacts directory of the build that is being promoted) see Promotions
- Optionally override the authentication credentials for each server in the job configuration (or provide them if they have not been provided for that server in the global configuration)
- Optionally retry if the transfer of files fails (useful for flakey connections)
- Enable the command/ script to be executed in a pseudo TTY
Build wrappers
There will be two new options in the Build Environment section of the job configuration
- Send files or execute commands over SSH before the build starts
This allows SSH to be used before a build begins, but after the workspace has been configured and source checked out
Most useful for maven project types - Send files or execute commands over SSH after the build runs
As long as the build was attempted, this will run after the build finishes, and will run whether the build is successful or not
This allows cleanup or shutdown of services started before or during the build
Use the publisher (Send build artifacts over SSH in Post-build Actions) to publish build artifacts from successful builds
Global Configuration
From the Jenkins home page, click "Manage Jenkins" and then click on "Configure System" and find the SSH section. It allows you to configure hosts that are later available in your builds.
Default settings
The SSH configuration section looks like this:
This configures the default key that will be used by all of the SSH
configurations.
The simplest way to configure the key is to paste an unencrypted key
into the Key box.
To configure, set either the path to a file containing the key
or paste the key into the Key field.
If you enter data into both Path to key and Key, the pasted Key will
take precedence and the Path to file will be ignored.
These settings are use for all hosts by default.
Unencrypted keys
If you plan to give read access to the Jenkins configuration page to non
administrators, then you should ensure that you only use private keys
encrypted with strong passphrases.
The passphrase itself will be encrypted when the configuration is saved,
and will also be encrypted in the UI so that the value cannot be read.
Passphrase
If the key is encrypted with a passphrase then set it here.
Path to file
The location, on the Jenkins master, of the private SSH key to use.
The path can be an absolute path to the key, or relative to the
JENKINS_HOME directory.
Key
Paste the private key into this box.
The key should include both the header and footer lines (----) and
everything in between.
Disable exec
This option will remove the ability to execute commands from this
plugin.
If this option is checked, then the Disable exec option in the Advanced
section of an SSH Server will be ignored.
Add an SSH Server
Click on the "Add" button next to "SSH Servers"
Fill in Name, Hostname, Username and Remote Directory. see Publish Over ... for common options for Host Configurations
Username
The user that will be used to connect to the host.
This user will need the public key in their authorized_keys file on the
remote host (if using public key authentication).
Advanced options
see Publish Over ... for common options for Host Configurations
Use password authentication, or use a different key
Selecting this option will produce 3 more configuration boxes that mirror the options available for the Jenkins SSH Key.
Passphrase / Password
If either Path to key or Key are configured then this is the passphrase
to use with the encrypted key.
If no key is configured then this is the password that will be used for
password authentication.
Path to key
See description above.
Key
See description above.
Disable exec
This option will remove the ability to execute commands using this configuration.
Add the public key to the remote server
Ensure that the public key (counterpart to the private key configured above) is in the authorized keys file for the user that you connect as on the server you want to connect to.
Check and save configuration
- Click "Test Configuration".
- Add more server configurations (if required)
- Save
Use SSH during a build
This plugin includes a builder which enables the use of the publisher during the build process.
This means that you can send newly created packages to a remote server
and install them, start and stop services that the build may depend on
and many other use cases.
Configure a job to Publish Over SSH
see Publish Over ... for common options for Server
see Publish Over ... for common options for Transfer Sets
Exec command
If there is anything in this configuration box then it will be executed
on the remote server.
If Source files are configured, then the files will be transfered before
the Exec command is executed.
If the exit status of the command is not zero, then the publish will
fail.
STDOUT and STDERR from the command execution are recorded in the Jenkins
console.
Source files, Exec command
You must configure Source files, Exec command or both.
If neither Source files nor Exec command are configured, the publish
will fail.
If the Source files box is empty then no files will be transferred.
Environment variables
Source files, Remove prefix, Remote directory and Exec command can all use the Jenkins environment variables and build parameters.
Advanced (Server)
Advanced (Transfer Sets)
see Publish Over ... for details of common options
Exec timeout (ms)
Configure a timeout for the Exec command to use.
If the command has not returned within this time then the publish will
fail.
Exec in pty
Run the Exec command in a pseudo TTY.
Advanced (Publisher)
If you click the "Advanced..." button that is immediately below the "Add Server" button, you will make more configuration options available.
see Publish Over ... for common options for Publisher
Options to override the default Promotion behaviour
If you are configuring an action in a promotion, new options will become available.
see Publish Over ... for common options for Promotions
Version History
Release notes are now recorded in Github Releases.
For older versions, refer to changelog.