Right Hook simplifies setting up a web app to handle GitHub repo hooks.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Right Hook

Build Status Code Climate Coverage Status Gem Version

Right Hook is a collection of tools to aid in setting up a web app to handle GitHub repo hooks.

To see some example usage, head over to right-hook/hookbooks.

To see the documentation for the current version of the gem, visit rubydoc.info.


Add this line to your application's Gemfile:

gem 'right_hook'

And then execute:

$ bundle

Or install it yourself as:

$ gem install right_hook


Your App

Create an application by subclassing RightHook::App:

#!/usr/bin/env ruby
# app.rb
require 'right_hook/app'
require 'right_hook/event'

class MyApp < RightHook::App
  # You must supply a secret for each repository and hook.
  # The secret should only be known by GitHub; that's how we know the request is coming from GitHub's servers.
  # (You'll specify that secret when you go through subscription.)
  def secret(owner, repo_name, event_type)
    if owner == 'octocat' && repo_name == 'Spoon-Fork' && event_type == RightHook::Event::PULL_REQUEST
      raise 'unrecognized!'

  # Code to execute for GitHub's pull request hook.
  # The secret has already been verified if your code is being called.
  # See app.rb and spec/app/*_spec.rb for signatures and examples of the valid handlers.
  def on_pull_request(owner, repo_name, action, pull_request_json)
    message = <<-MSG
      GitHub user #{pull_request_json['user']['login']} has opened pull request ##{pull_request_json['number']}
      on repository #{owner}/#{repo_name}!
    send_text_message(MY_PHONE_NUMBER, message) # or whatever you want

You'll need to host your app online and hold on to the base URL so you can subscribe to hooks.

GitHub Authentication

To create hooks on GitHub repositories, you need to be authenticated as a collaborator on that repository. GitHub's UI currently only supports configuring push hooks, so you'll want to authenticate through Right Hook to set up custom hooks.

Right Hook never stores your password; instead, it always uses OAuth tokens. The only time it asks for your password is when it is creating a new token or listing existing tokens.

Right Hook doesn't store your tokens, either. It's your duty to manage storage of tokens. Typically, tokens and other secret values are stored as environment variables for your app, rather than in a flat file or in a database.

Here's one way you can generate and list tokens:

#!/usr/bin/env ruby
require 'right_hook/authenticator'

puts "Please enter your username:"
username = $stdin.gets

# Prompt the user for their password, without displaying it in the terminal
authenticator = RightHook::Client.interactive_build(username)

# Note for the token (this will be displayed in the user's settings on GitHub)
note = "Created in my awesome script"

authenticator.authorizations.each do |token|
  puts "Token: #{auth.token}\nNote: #{auth.note}\n\n"

Subscribing to Hooks

Right Hook provides a way to tell GitHub you want to subscribe your Right Hook application to GitHub's hooks. It's easy!

#!/usr/bin/env ruby
require 'right_hook/subscriber'

default_opts = {
  base_url: "http://right-hook.example.com",
  oauth_token: ENV['RIGHT_HOOK_TOKEN']

subscriber = RightHook::Subscriber.new(default_opts)

  owner: 'octocat',
  repo_name: 'Hello-World',
  event_type: RightHook::Event::PULL_REQUEST,
  secret: 'secret_for_hello_world'

(For more details, consult the RDoc documentation.)


Available under the terms of the MIT license. See license.txt for details.


Is any documentation unclear? Did you expect that Right Hook was going to help you in a particular way, and then it didn't? Please open an issue! One of the best ways to improve open source software is to make your needs known.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request