Hooks

Defining a Hook

Warehouse::Hooks.define :example_hook do

Defines a hook named “Example Hook” when displayed on the Hooks page.

Hook Options

option :option_name, "a description"

You can also pass options like: :as => :boolean or :label => "Some Label", these options are passed to Formtastic – so you could use any type of field or any other options available. Boolean fields will automatically be place after all other fields.

Initialize Block

init do
  require 'somelibrary'
end

This block is run when the application starts up – so you want to require any required gems/libraries/code/etc.. here. Also, you will need to add gems you need to the Gemfile for bundler.

Run Block

run do
  # do something
end

This block is run when the hook is run – this is where the magic happens. You have access to two variables provided by the hook, payload and data. They are both hashes but have to be traversed in different ways. The hash we use to generate the payload looks like:

{
  :before     => before,
  :after      => after,
  :ref        => ref,
  :commits    => [{
    :id        => commit.id,
    :message   => commit.message,
    :timestamp => commit.committed_date.xmlschema,
    :url       => commit_url,
    :added     => array_of_added_paths,
    :removed   => array_of_removed_paths,
    :modified  => array_of_modified_paths,
    :moved => array_of_moved_paths
    :author    => {
      :name  => commit.author.name,
      :email => commit.author.email,
      :avatar => gravatar_for_author,
    }
  }],
  :repository => {
    :name        => repository.name,
    :url         => repo_url,
  }
}

So you need to access the payload like payload[:repository][:name]. However, data would look something like

{
  "ssl" => "1",
  "api_key" => "api_key",
  "subdomain" => "",
}

So you would have to do data['api_key'].

Notice: payload uses symbols while data uses strings

The Future

On the Roadmap

help do
  EOF
    <h3>Some Help</h3>
  EOF
end

This planned feature would allow a hook to display help on the hook page. Not set for a release – possibly 2.0 but not likely.

Possibilities

Allow the hook to define controller actions and links to be added in between the Update Hook button and test button setting. A feature I would like to implement. Would enable hooks like Twitter to use OAuth to use callback so users don’t have to save their passwords in the database.