Jenkins : Publish Over SSH Plugin

Plugin Information

View Publish Over SSH on the plugin site for more information.

This plugin is up for adoption. Want to help improve this plugin? Click here to learn more!

Publish Over ...

Read Publish Over wiki page first

Please read Publish Over first.
Common configuration options that are documented in the Publish Over wiki page will not be repeated here.

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

  1. 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
  2. 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 succesful builds

Configure

Create host configurations in the main Jenkins configuration

From the Jenkins home page, click "Manage Jenkins" and then click on "Configure System"

Find the SSH section (as below)

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.

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.

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

Change log

1.14 (24/03/2016)

  • JENKINS-29360 Bumped the version of jsch to overcome algorithm issue
  • Add support for proxies (PR #10)

1.13 (19/05/2015)

  • Implement methods for adding and removing host configurations (PR #5)

1.12 (16/10/2014)

  • Don't blow up errors when interacting with Item.EXTENDED_READ (PR #8)

1.11 (30/12/2013)

  • JENKINS-17058 Publish over SSH plugin XML configuration cannot be read on Jenkins start up.

1.10 (03/03/2013)

  • JENKINS-16681 Allow source file names and paths to contain whitespace
    • Add Advanced Transfer Set option "Pattern separator"

1.9 (22/10/2012)

  • JENKINS-13831 Option to create empty directories
  • No default excludes option now available for all versions of Jenkins
  • Exclude files pattern now available for all versions of Jenkins

1.8 (10/09/2012)

  • JENKINS-13693 Add option to disable default excludes
  • Prefix Publish over to the global config section title
  • Move the defaults configuration in the global config to an Advanced section

1.7 (08/05/2012)

  • Fixed JENKINS-13714 Drag and drop handle missing from transfer sets

1.6 (06/02/2012)

  • Upgrade JSch from 0.1.44 to 0.1.45
  • Remove gssapi-with-mic as a preferred auth method

1.5 (10/11/2011)

  • Enable the server credentials to be specified/overriden when configuring the publisher in a job

1.4 (11/09/2011)

1.3 (05/08/2011)

  • JENKINS-10599 When using the Flatten files option, do not create the Remote directory if there are no files to transfer

1.2 (21/07/2011)

  • JENKINS-10315 Only open an SFTP connection if any of the transfer sets have source files configured
    • Saves time and resources on client and server
    • Enables the plugin to run commands on servers that do not support SFTP
  • JENKINS-10363 Allow the publisher default values to be changed in Manage Jenkins (on Jenkins and Hudson 1.391 - 1.395)

1.1 (09/07/2011)

1.0 (08/07/2011)

0.14 (06/06/2011)

  • Fixed JENKINS-9878 where the password/passphrase for an individual configuration was ignored when saving the global config (Manage Jenkins)

0.13 (20/05/2011)

  • Remove "Give the master a NODE_NAME" option when running on Jenkins 1.414 or later
  • Default the "Give the master a NODE_NAME" option to 'master' when run on a Jenkins older than 1.414

0.12 (09/05/2001)

  • Advanced Transfer Set option to Exclude files
    (option only available with Jenkins 1.407 and later)
  • JENKINS-9480 Exec command is now an expandable textarea

0.11 (15/04/2011)

  • Fixed form validation issue (JENKINS-9376) when selected configuration name contains non ASCII characters

0.10 (14/04/2011)

  • Fix potential NPE when performing ajax form validation

0.9 (10/04/2011)

  • Reduce horizontal space taken up by labels in the configuration views

0.8 (10/04/2011)

  • Add options to disable exec for individual configurations, or for the whole plugin

0.7 (01/04/2011)

  • Enable form validation for SSH key file location for Jenkins 1.399 and later

0.6 (07/03/2011)

  • Fixed JENKINS-8982 where configuration for the builder was not populated when re configuring a job

0.5 (18/02/2011)

  • Passwords/passphrases encrypted in config files and in UI (now requires Hudson > 1.384 or any Jenkins)
  • Environment variables for substitution now include build variables (including matrix build axis)
  • Added build wrapper to enable SSH before a (maven) project build, or to run after a build whether the build was successful or not

0.4 (16/02/2011)

  • Added form validation
  • Removed debug logs for new configurations

0.3 (11/02/2011)

  • 2 new configuration options when in promotion
    • Use the workspace when selecting "Source files"
    • Use the time of the promotion when using "Remote directory is a date format"

0.2 (10/02/2011)

  • Stop the builder from showing up in promotion actions as publisher already included

0.1 (08/02/2011)

  • Initial release

Questions, Comments, Bugs and Feature Requests

Please post questions or comments about this plugin to the Jenkins User mailing list.
To report a bug or request an enhancement to this plugin please create a ticket in JIRA.