github-hooker
This is an internal gem at Plataformatec (http://plataformatec.com.br).
We use it to create and delete hooks in our github repositories (like campfire notifications for push and pull_request and CI integration with web push hooks).
Configuration
First, create ~/.github-hooker.yml
with
user: github_username
password: github_password
campfire_token: campfire_api_token
#optional api_url, default https://api.github.com
#api_url: https://mygithubenterprise/api/v3
Then you can use the command github-hooker
to list, create email, web and campfire hooks or delete them. Other hooks are not yet implemented (pull requests are appreciated!).
Why I need to write my password?
The hook API is only accessible by the v3 Github API. There's a Oauth2 authentication method, but in order to use that you would need to set up a new application with Github, and then collect the token by an http callback (that must be accessible on the web). For the sake of simplicity, we use the other way to authenticate (http auth basic).
Usage
The user specified MUST have administration rights for the repositories you want to set/delete hooks.
The available commands are:
$ github-hooker
Tasks:
github-hooker help [TASK] # Describe available tasks or one specific task
github-hooker list user/repo # List hooks in the given repository
github-hooker email user/repo events --address=ADDRESS # Add an email hook in the given repository. Events must be separated by commas.
github-hooker web user/repo events --url=URL # Add a web hook in the given repository. Events must be separated by commas.
github-hooker campfire user/repo events --room=ROOM --subdomain=SUBDOMAIN # Add a campfire hook in the given repository. Events must be separated by commas.
github-hooker delete user/repo hook_number # Delete the hook from the given repository
List hooks
github-hooker list plataformatec/devise
Create a new email hook
github-hooker email plataformatec/devise "push" [email protected]
Create a new web hook
github-hooker web plataformatec/devise "pull_request, push" --url=http://mycallback.com/callback
This creates a new web hook that calls the url specified by --url
. The events that this hooks listens must be the third argument and they must be separeted by commas.
Create a new campfire hook
github-hooker campfire plataformatec/devise pull_request,push,issue_comment --room="My Room" --subdomain="My Subdomain"
Creates a new campfire hook. The token used for authentication with Campfire must be provided in your ~/.github-hooker.yml
(see Configuration above).
Delete a hook
github-hooker delete plataformatec/devise 1010
Deletes the hook 1010 from the given repository. You can get the hook id from the url listed in github-hooker list user/repo
.
Events
The available events that github gives us are:
Email events:
- push
Campfire events:
- push
- pull_request
- issues
Web events:
- push
- pull_request
- issues
- issue_comment
Github's documentation about hooks (http://developer.github.com/v3/repos/hooks/ and https://api.github.com/hooks) does not have all these hooks listed, but they are working with us.
Naming
This gem is named after the famous Hooker Telescope, in operation in the Mount Wilson Observatory. Edwin Hubble used this telescope to discover the expansion of the universe.
License
MIT License. Copyright 2012 Plataformatec. http://plataformatec.com.br