Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Mary Poppins

    Build Status

    bad photoshop

    What's Poppin'?

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


    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.

    Finding Plugins

    Search for plugins via npm:

    npm search poppins-

    Some existing plugins are:

    Installing Plugins

    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 = { /*...*/ };

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

    Configuring the Plugin

    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.

    Let's get Poppin'

    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.

    Note: You need to use this command to install the hook. Using the web-based panel for hooks will not set the correct options.

    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:

      active: true

    Alternatively, you can remove the hook by visiting "" and clicking "remove."

    bad photoshop


    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.

    Programatic API

    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: '',
        port: 1234

    See example-config.js.


    Poppins is an EventEmitter.


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

    Authoring Plugins

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

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

    Developing Mary Poppins


    See Also

    • haunt - A module for creating github issue bots
    • metahub - github metadata cache/mirror
    • lmvtfy – a bot for doing static analysis





    npm i mary-poppins

    Downloadslast 7 days







    last publish


    • avatar