Gwooks
A DSL for quickly creating endpoints for GitHub post-receive webhooks. It makes it easy to perform some actions whenever one of your GitHub repos receives a push matching someone custom conditions.
Installation
Add this line to your application's Gemfile:
gem 'gwooks'
And then execute:
$ bundle
Or install it yourself as:
$ gem install gwooks
Usage
First extend the Gwooks::Base
class and use the DSL to create actions to be performed in response to a push:
class MyHookHandler < Gwooks::Base
repository_name "my_cool_project" do
# this block gets executed when GitHub receives
# a push to a repo named "my_cool_project"
# Here you can also access the payload sent by GitHub:
contributors = payload["commits"].map { |c| c["author"]["name"] }
send_email "[email protected]", "my_cool_project received changes by: #{ contributors.join(', ') }"
end
/Bump new version v(\d+\.\d+\.\d+)/ do |matches|
# this block gets called when GitHub receives a push
# with at least one commit message matching the Regexp.
matches.each do |match|
send_email("[email protected]", "New version released: #{match[1]}")
end
end
private
def send_email(to, msg)
# assume we define here a method to send an email
end
end
Then set up an application providing an endpoint for the GitHub post-receive webhook and make use of the class you created:
require "sinatra"
post "/webhook" do
MyHookHandler.call(params[:payload])
end
Alternatively, you can use the sinatra application provided by the class Gwooks::App
:
# In your config.ru
require "gwooks"
# Tell Gwooks::App to use your class
Gwooks::App.use_webhook MyHookHandler
# Gwooks::App sets up an endpoint on POST /"
run Gwooks::App
Finally set up your GitHub repo to trigger a post-receive hook pointing to your endpoint. Whenever GitHub receives a push, your endpoint will be notified, and all the matching actions will be performed.
DSL methods
Each DSL method matches a corresponding property in the payload sent by the GitHub post-receive hooks
(e.g. repository_owner_email
matches payload["repository"]["owner"]["email"]
). Note that all the methods
starting with commits
are also aliased with the singular commit
to improve code readability.
The signature is identical for all methods:
dsl_method_name(pattern, &block)
pattern can be any object. If it is a Regexp, it is matched against the target property in the payload, otherwise it is checked for equality.
block is called passing the match, or array of matches if the target property is an array (which is, in all commit* methods). The match is a MatchData object when regexp matching is used, or the matched pattern otherwise.
Here is the full list of the DSL methods:
after
before
commits_added (alias: commit_added)
commits_author_email (alias: commit_author_email)
commits_author_name (alias: commit_author_name)
commits_id (alias: commit_id)
commits_message (alias: commit_message)
commits_modified (alias: commit_modified)
commits_removed (alias: commit_removed)
commits_timestamp (alias: commit_timestamp)
commits_url (alias: commit_url)
ref
repository_description
repository_forks
repository_homepage
repository_name
repository_owner_email
repository_owner_name
repository_pledgie
repository_private
repository_url
repository_watchers
Beta
Please take into consideration that this is a beta release, and as such the API may change