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:
You should see it come back to you with a prompt:
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:
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
-tswitch to keep tailing them
heroku configto see the environment variables you have already configured
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).