Deployment using grunt.

npm install grunt-shipit
26 downloads in the last week
57 downloads in the last month

grunt-shipit Build Status

Deploy using grunt task.

Getting Started

This plugin requires Grunt ~0.4.0

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-shipit --save-dev

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



grunt shipit:<stage> <tasks ...>



  • git 1.7.8+
  • rsync 3+
  • OpenSSH 5+


  • GNU coreutils 5+

Shipit task

Run task

grunt shipit:<stage> <tasks ...>



Type: String

Define the local working path of the project deployed.


Type: String

Define the remote path where the project will be deployed. A directory releases is automatically created. A symlink current is linked to the current release.


Type: String

Git URL of the project repository.


Type: String

Tag, branch or commit to deploy.


Type: Array<String>

An array of paths that match ignored files. These paths are used in the rsync command.


Type: String

Number of release to keep on the remote server.


Type: String or Array<String>

Servers on which the project will be deployed. Pattern must be if user is not specified ( the default user will be "deploy".

Usage example

shipit: {
  options: {
    workspace: '/tmp/github-monitor',
    deployTo: '/tmp/deploy_to',
    repositoryUrl: '',
    ignores: ['.git', 'node_modules'],
    keepReleases: 2
  staging: {
    servers: ''

To deploy on staging, you must use the following command :

grunt shipit:staging deploy

You can rollback to the previous releases with the command :

grunt shipit:staging rollback


Shipit has several events describe in the workflow, you can add custom event and listen to events.

grunt.registerTask('build', function () {
  // ...

grunt.shipit.on('fetched', function () {['build']);


shipit.local(command, [options], callback)

Run a command locally and streams the result.

shipit.local('ls -lah', { cwd: '/tmp/deploy/workspace' }, function (err, stdout) {
  // ...

shipit.remote(command, [options], callback)

Run a command remotely and streams the result.

If you want to run a sudo command, the ssh connection will use the TTY mode automatically.

shipit.remote('ls -lah', function (err, stdout) {
  // ...

shipit.remoteCopy(src, dest, callback)

Make a remote copy from a local path to a dest path.

shipit.remoteCopy('/tmp/workspace', '/opt/web/myapp', function (err) {
  // ...


Shipit attach several variables during the deploy and the rollback process :


All options describe in the config sections are avalaible in the shipit.config object.


Attached during deploy:fetch task.

You can manipulate the repository using git command, the API is describe in gift.


Attached during deploy:update and rollback:init task.

The current release dirname of the project, the format used is "YYYYDDMMHHmmss" (moment format).


Attached during deploy:update and rollback:init task.

The remote releases path.


Attached during deploy:update and rollback:init task.

The complete release path : path.join(shipit.releasesPath, shipit.releaseDirname).


Attached during deploy:publish and rollback:init task.

The current symlink path : path.join(shipit.config.deployTo, 'current').

Workflow tasks

  • deploy
    • deploy:init
      • Emit event "deploy".
    • deploy:fetch
      • Create workspace.
      • Initialize repository.
      • Add remote.
      • Fetch repository.
      • Checkout commit-ish.
      • Merge remote branch in local branch.
      • Emit event "fetched".
    • deploy:update
      • Create and define release path.
      • Remote copy project.
      • Emit event "updated".
    • deploy:publish
      • Update symlink.
      • Emit event "published".
    • deploy:clean
      • Remove old releases.
      • Emit event "cleaned".
  • rollback
    • rollback:init
      • Define release path.
      • Emit event "rollback".
    • deploy:publish
      • Update symlink.
      • Emit event "published".
    • deploy:clean
      • Remove old releases.
      • Emit event "cleaned".



npm loves you