Mary Poppins is an extensible GitHub bot that keeps your PRs and issues tidy.

See also:

• haunt - A module for creating github issue bots
• metahub - github metadata cache/mirror

Install mary-poppins via npm:

npm install -g mary-poppins

The config file is just JavaScript. See example-config.js.

To create a new config in the current directory from the example, you can run:

mary-poppins init

By herself, Mary Poppins don't do anything interesting. By loading plugins you can give her things to do.

Search for plugins via npm:

npm search poppins-

Some existing plugins are:

• poppins-pr-checklist - respond to pull requests with a checklist
  • poppins-check-cla - check if a user has signed a CLA
  • poppins-check-commit - check if the commits follow conventions

Plugins should be installed locally, in the same directory as the config file. Plugins are installed with npm:

npm install poppins-pr-checklist --save

Typically you want to save the plugin to package.json.

After installing the plugin, you need to load it by calling poppins.couldYouPlease() in your config file:

// config.js
module.exports = function (poppins) {

  poppins.config = { /*...*/ };

  poppins.couldYouPlease('pr-checklist');
};

Alternatively, poppins can load all of the plugins in the node_modules directory with poppins.theUsualPlase().

Plugins are configured by adding properties to a Poppins object. By convention, plugins add properties to poppins.plugins.pluginName, where pluginName corresponds to the name of the plugin.

Mary Poppins needs to be hosted somewhere so that Github hooks can send her updates. I recommend something like Google Compute Engine, Linode, or Amazon EC2. Any service that allows you to run node and gives you a static IP/hostname is fine.

To run Poppins, need to add the appropriate Github repository hook. The mary-poppins CLI can do this for you. Run:

mary-poppins install config.js

If you need to make changes to the config, uninstall then re-install.

Once Mary Poppins's GitHub hook is installed, you can have her respond to PRs like this:

mary-poppins start config.js

If you want to stop Mary Poppins, you'll also need to remove the corresponding Github Webhook.

You can uninstall the web hook by running the following:

mary-poppins remove config.js

To verify that the hook isn't there anymore, you can run:

mary-poppins hooks config.js

Which will log something like this:

#12345678
  active: true
  url:    http://example.com:3000/

Alternatively, you can remove the hook by visiting "https://github.com/**you**/**your-repo**/settings/hooks" and clicking "remove."

Mary Poppins caches Github repo data to reduce the number of Github calls she needs to make. This cache is stored in .cache by default. mary-poppins is pretty good at knowing when she has a dirty cache, but you can remove this directory if you'd like to.

The programmatic API is useful for authoring plugins. If you don't need to interact with Mary Poppins's plugins, you might be better off using metahub.

Useful for extending Poppins. Note that Poppins extends metahub and is an EventEmitter.

var util = require('util');
var Poppins = require('poppins').Poppins;

var MrsFeatherbottom = function () {};
util.inherits(MrsFeatherbottom, Poppins);

var nanny = new MrsFeatherbottom({});

var config = { /* ... */ };
var poppins = require('poppins')(config);

An express instance that listens for updates from Github's web hook.

Core config options:

config = {
  target: {
    user: 'myname',
    repo: 'myrepo'
  },
  login: {
    username: 'myrobotname',
    password: 'supersecretpassword'
  },
  hook: {
    url: 'http://example.com:1234',
    port: 1234
  }
};

See example-config.js.

Poppins is an EventEmitter.

poppins.on('pullRequestOpened', function (data) { /*...*/ }

Plugins are simply functions that add properties or listeners to a Poppins object.

Take a look at poppins-pr-checklist for an example.

MIT