Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

grunt-ssh-deploy (Version: 0.4.1)

SSH Deployment for Grunt using ssh2.

Getting Started

This plugin requires Grunt ~0.4.4

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-ssh-deploy --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:


The tasks


In your project's Gruntfile, add a section named environments to the data object passed into grunt.initConfig().

  environments: {
    environment: {
      // Environment specific options here

This plugin will connect to your remote host, add a directory to releases/ in your remote_path, and create a symlink to the latest release.

The symlink by default is current, you can change this by setting current_symlink.


By setting an environment, you can deploy each specific one with grunt ssh_deploy:environment or rolling back with grunt ssh_rollback:environment.


Type: String

Remote host to connect to.


Type: String

The username to connect as on the remote server.


Type: String

Password for the username on the remote server.


Type: string

Path to your private key privateKey: require('fs').readFileSync('/path/to/private/key')


Type: string

Passphrase of your private key if needed.


Type: string

Set agent agent: process.env.SSH_AUTH_SOCK


Type: String Default value: '22'

Port to connect to on the remote server.


Type: Number Default value: 20000

Default timeout (in milliseconds) to wait for the SSH handshake to complete.


Type: String

Full path on the remote server where files will be deployed.


Type: String

Path on your local for the files you want to be deployed to the remote server. No trailing slash needed.


Type: String Default value: 'current'

Path to directory to symlink with most recent release.

options.before_deploy, options.after_deploy

Type: String

Commands to run on the server before and after deploy directory is created and symlinked.


Type: String|function Default value: the current date (as a timestamp)

The release tag, e.g. '1.2.3'. It can be a string or a function (in that case is called and the returned value will be used). It defaults to the current timestamp formatted as 'YYYYMMDDHHmmssSSS'.

WARN: release tag name matters. When used with parameter releases_to_keep the releases are reverse sorted alphabetically and older ones are removed. So be careful when you set your release tag name.


Type: Number

The number of builds (including the current build) to keep in the remote releases directory. Must be >= 1.


Type: String Default value: '/'

Name of the sub directory to store the release in. Useful when multiple projects get deployed to the same machine and the releases_to_keep option is being used.


Type: String Default value: 'releases'

Name of the root directory where all the releases are published. If a options.release_subdir is also provided then the latest will be appended after this path.


Type: Boolean Default value: false

Compress the build before uploading.


Type: Number Default value: 200 * 1024

Largest amount of data allowed on stdout or stderr.


Type: Array Default value: []

List of folders or files to exclude from build.

Usage Examples

Custom Options

  // do not store credentials in the git repo, store them separately and read from a secret file
  secret: grunt.file.readJSON('secret.json'),
  environments: {
      options: {
        local_path: 'dist',
        current_symlink: 'current',
        deploy_path: '/full/path'
      staging: {
          options: {
              host: '<%= %>',
              username: '<%= secret.staging.username %>',
              password: '<%= secret.staging.password %>',
              port: '<%= secret.staging.port %>',
              debug: true,
              releases_to_keep: '3'
      production: {
          options: {
              host: '<%= %>',
              username: '<%= secret.production.username %>',
              password: '<%= secret.production.password %>',
              port: '<%= secret.production.port %>',
              releases_to_keep: '5',
              release_subdir: 'myapp'

Before and After Hooks

  environments: {
    options: {
      local_path: '.',
    production: {
      options: {
        host: '',
        username: 'root',
        password: 'password',
        deploy_path: '/sites/great_project',
        before_deploy: 'cd /sites/great_project/releases/current && forever stopall',
        after_deploy: 'cd /sites/great_project/releases/current && npm install && forever start app.js'

Release History

  • 2014/06/23 - v0.2.0 - Added rollback functionality.
  • 2014/06/19 - v0.1.7 - Fixed symlink method to cd into deploy_path before setting symlink.
  • 2014/05/04 - v0.1.5 - Changing symlink method to not use full path.
  • 2014/05/04 - v0.1.0 - Initial release.