It took me far too long to get my first hubot working; when I finally sat down to get it going the process was much easier than I expected! So here’s a little guide in the hope that this helps you get started too.

Running Hubot Locally

The documentation is quite good, although I found that without any coffeescript or nodejs experience it did skate over some things that, as a PHP developer, I didn’t know. So begin with the docs: https://github.com/github/hubot/blob/master/docs/README.md.

Hubot needs node and npm locally, and the installation docs walk you through installing yeoman which is a great way of setting up a project. Once you are installed, your bot will be able to run locally (we’ll deploy to heroku later) and talk to you:

./bin/hubot

You should see it come back to you with a prompt:

Hubot> 

and you can say hello:

Hubot> hubot ping
Hubot> PONG

It’s alive :)

This would be a great moment to git init and make an initial commit before you change anything!

Adding Scripts to Hubot

It seems like the world of hubot scripts is in disarray, there used to be a repository for them but there are so many that this was a bit chaotic, so now there’s an organisation for hubot scripts: https://github.com/hubot-scripts. Some of the older scripts haven’t been moved over, however, and plenty of others have their homes on their owners github accounts. This can make it hard to find things.

There are two main ways of adding scripts to hubot: a packaged script from npm, and by adding code into your hubot directly.

The npm method is the easiest, if you can find the plugin you want (try https://www.npmjs.com/search?q=hubot) then you simply add the plugin to the packages.json file in the root of your hubot, and run npm install. Then all you have to do is add the name of the package to the list in external-scripts.json, and restart your hubot. If your new plugin adds any commands to the hubot, you’ll see them when you type:

hubot help

The other method is to add the coffeescript directly to your directory (I’m using submodules so that I can use the changes I make in multiple projects, I’ll write a separate post about that). Take the *.coffee file and add it to the scripts/ directory. You don’t need to manually include it; hubot will see and try to use all the scripts in that directory. Of course you don’t need to rely on existing scripts; even without JS experience I found the coffeescript plugins quite approachable and there are lots and lots of examples around.

Some scripts register commands, others offer endpoints that are very useful when combined with the webhooks that are offered by so many systems. Although it’s possible to test webhooks on your local machine, we’ll just move straight on and deploy the bot to heroku.

Deploy to Heroku

This part of the documentation I thought was great, so you can just read it! https://github.com/github/hubot/blob/master/docs/deploying/heroku.md. A few things that I didn’t know about Heroku:

• You can see the logs with heroku logs, and add a -t switch to keep tailing them
• Use heroku config to see the environment variables you have already configured

The Procfile is what holds the settings that heroku will use to run your bot, so you’ll probably set both its name and the adapter here. For example I have a procfile that looks like this:

web: bin/hubot -a irc -n joindin-hubot

You deploy the bot by pushing to the git repository on heroku, and then you can share your new robot friend with the world (or maybe just your team).