Pushmaster

Pushmaster is a helper script that makes it trivial to listen to Github Post-Receive hooks.

The idea is that you deploy pushmaster on your server, add pushmaster as a post receive hook on Github repositories, and have pushmaster execute a ruby script (/path/to/pushmaster/listeners/[repository name].rb) whenever you push to that Github repository.

If pushmaster is deployed to https://pushmaster.yoursite.com/, and you push to the repository https://github.com/you/my-repo, Github will ping pushmaster and pushaster will in turn execute listeners/my-repo.rb.

Use cases

Deploying applications

I use pushmaster to deploy my homepage. Here’s my listener, listeners/homepage.rb:

Dir.chdir "/home/leethal/www/homepage" do
  git "pull"
  touch "tmp/restart.txt"
end

Posting to services not on Github’s list of services

Github can already send messages to IRC, Basecamp, FogBugz and many more when you push to a Github repository. Pushmaster makes it easy to implement similar hooks for services that aren’t on that list, such as properitary internal tools.

Here’s an example of a listener that pings an internal tool that lives at localhost:5892

require 'net/http'
require 'cgi'
url = URI::HTTP.build({
  :host => "localhost", :port => "5892",
  :query => "num_commits=#{data["commits"].length}&ref=#{data["ref"]}"
})
Net::HTTP.get_response(url)

…if you can dream it, you can do it!

The listeners are plain Ruby scripts, so you can basically run whatever Ruby code you can imagine. Because pushmaster is password protected, it also runs in a secure environment.

Getting started

Here’s a few steps you need to go through in order to get started.

1. Deploy pushmaster on your server. A sensible setup is on a subdomain such as https://pushmaster.yourdomain.com/. Pushmaster is a Sinatra application, look here for more on deploying pushmaster on your server.
2. Create a settings.yml and set the username and password. See settings.yml.sample.
3. Add a listener, listeners/[Github repository name].rb. For https://github.com/you/the-repo, the listener is named listeners/the-repo.rb.
4. In the configuration panel of your Github repository, add https://user:password@pushmaster.yourdomain.com/ as a “Post Receive URL”.

And you’re ready to go!

The listener DSL

Besides all the methods that comes with Ruby, there are a few DSL-like commands added by pushmaster that you can use in your listeners.

• git — runs a git command
• touch — creates a file
• run — executes a system command
• log — logs a message to log/your-repository.log

Other than that, it’s Just Ruby™. Have fun, go mad!