grunt-alert

Sends alerts about failing builds using different channels

Getting Started

This plugin requires Grunt ~0.4.5

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

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

grunt.loadNpmTasks('grunt-alert');

The "alert.hook" task

Can be used as a dependency for other tasks. The alert.hook task patches the grunt.warn and grunt.fatal functions to trigger a child process that takes care of notifying about errors using the alert tasks.

The child process is spawned as a detached process and therefore runs asynchronously and most likely will finish after the main grunt process ends.

Example

//A task that just fails
grunt.registerTask('fatal', 'tests fatal failure', function(){
    grunt.fatal('this task has failed with a fatal error. you will all die.');
});
 
//When this task runs, before the fatal task is triggered grunt.fatal
//is patched so errors are captured and alerts are triggered.
grunt.registerTask('catchfatal', ['alert.hook', 'fatal']);

The "alert.event.hook" task

Can be used as a dependency for other tasks. The alert.event.hook task patches the grunt.warn and grunt.fatal functions to emit events via grunt.event when a task triggers an error.

grunt-alert triggers only one event, the alert event. Arguments are:

• type: can be warn or fatal
• error: the error message logged by the failing task
• errorcode: the error code logged by the failing task

Example

grunt.registerTask('useemitter', 'tests fatal failure', function(){
    grunt.log.writeln('Registering event handlers');
    grunt.event.on('alert', function(type, error, errorcode){
        console.log(arguments);
    });
});
 
grunt.registerTask('warn', 'tests warn failure', function(){
    grunt.warn('this task has failed with a warning. i guess you\'ll survive');
});
 
grunt.registerTask('warnevent', ['alert.event.hook', 'useemitter', 'warn']);

The result is the following:

➜ grunt warnevent

Running "alert.event.hook" task
injecting emitter hooks

Running "useemitter" task
Registering event handlers

Running "warn" task
{ '0': 'warn',
  '1': 'this task has failed with a warning. i guess you\'ll survive',
  '2': 1 }
Warning: this task has failed with a warning. i guess you'll survive Use --force to continue.

The "alert" task

Triggers an alert using the configured platforms.

General rules on platform configurations

Types

If type is set, it will be used that as the alerting platform name. If not the plugin will try to use the target name as the platform name.

This basically means that

alert: {
   foo: { type: 'slack' }
}

is equivalent to

alert: {
   slack: {}
}

Message and placeholders

Every platform type supports a message property that can include a string placeholder %s. That placeholder will be replaced, in order of priority, with:

1. whatever is passed as command-line argument with --arg=<string> when the task is invoked directly
2. or the error message that is generated by a failing task when the alert task is automatically triggered by the alert hook on task fail (warn or fatal) events.

Logging

It is possible to configure the alert tasks to output logging information into a file. This way even when alert tasks run in a separate process it is possible to look at the logs later on and see if any error happened.

With the log property it is possible to specify the destination file for the log entries.

Supported platform types

Slack

alert: {
    slack: {
        type: 'slack',
        webhookUrl: '',
        channel: '#grunt', //optional
        username: 'Grunt Alert', //optional
        iconUrl: '', //optional
        iconEmoji: ':ghost:', //optional
        message: 'Ya\'ll suck. The build just failed with this error: %s',
        log: 'somefile.log' //optional
    }
}

Hipchat

alert: {
    hipchat: {
        room: 'grunt',
        token: '', //A token with send_notification scope for the room
        messageFormat: 'text', //Default is html as per API spec
        message: 'Ya\'ll suck. The build just failed with this error: %s',
        notify: true, //Default is false as per API spec
        color: 'red', //Default is yellow as per API spec. Valid values are yellow, green, red, purple, gray, random.
        log: 'somefile.log' //optional
    }
}

Twilio

It is possible to send SMS notifications via Twilio. You will have to register for a Twilio account. You can start with the free trial account, which requires to add and verify every destination phone number.

twilio: {
    to: '[phone]',
    from: '[phone]',
    message: 'Ya\'ll suck. The build just failed with this error: %s',
    account: '',
    token: '',
    log: 'somefile.log' //optional
}

Continuos Integration

grunt-alert is especially useful when used with a continuos integration (CI)setup. If something goes wrong with the build your CI server can use grunt-alert to notify you using your favorite platforms.

Jenkins

Jenkins has a feature called ProcessTreeKiller. This is slightly problematic as the alert hook spawns the alert task as a detouched process, which will be killed by Jenkins as soon as the main build process ends. To prevent this from happening and ensure that your notifications go through, when you configure your build make sure that you change the BUILD_ID environment variable (e.g. BUILD_ID=dontKillMe).

Below is an example of Jenkins configuration for an example project.