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
, and
those starting with repository
are aliased with repo
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 (alias: repo_description)
repository_forks (alias: repo_forks)
repository_homepage (alias: repo_homepage)
repository_name (alias: repo_name)
repository_owner_email (alias: repo_owner_email)
repository_owner_name (alias: repo_owner_name)
repository_pledgie (alias: repo_pledgie)
repository_private (alias: repo_private)
repository_url (alias: repo_url)
repository_watchers (alias: repo_watchers)
Beta
Please take into consideration that this is a beta release, and as such the API may change
Changelog
v0.0.3 - Alias repository_
methods to repo_
v0.0.2 - Alias commits_
methods to commit_
v0.0.1 - First release