GitHub offers a great feature called WebHook URLs. You can add a url to take advantage of git’s post-receive hook and get a POST request containing data related to a repository push (e.g., commits, tags, and head-resets). While the data is very detailed and thorough, its complexity and focus on mimicking the git operations make it harder to use. For example, files added are listed per commit instead of a complete array spanning all commits. Also, retreiving if a tag was added requires checking three different properties.
When using GitHub payloads to determine your own server behavior, different payload data from GitHub may require different actions to be taken. For example, you wouldn’t need to pull from your master branch and update a website’s content if someone pushed a new branch. But you might want to stage that branch somewhere, which would be a completely different operation.
We use the post-receive hooks GitHub provides for many of our websites, including bocoup.com. All of us work on the Bocoup.com website collaboratively, and so when any of us commits to our website’s repository, GitHub sends that action to our web server. We have some scripts in place to pull that repository into a staging area, which allows all of us to preview the changes. When it’s time to go live, there is a separate page we can access that lets us deploy the current staging commit to the live site. It’s all pretty basic, but it saves us an incredible amount of time.
I wanted to build and share a tool that addresses the problems of complexity and filtering the raw GitHub payload, and I was able to go above and beyond my normal open source time here at Bocoup to go ahead and do that! Cool, eh?
The result of this work is
gith, short for “githooks”. It provides an easy-to-use API that simplifies
the process of utilizing GitHub’s payloads in a number of ways:
gith accomplishes this very well. For example, if I wanted to do something when a file was added
to a particular repository, I can write a small node script to handle it:
or if I wanted to find files added in a particular directory:
or even more simply, get alerted when anything happens:
There’s a lot more information at the project’s repository: https://github.com/danheberden/gith
gith is the result of refining the development and deployment workflow for bocoup.com
and many of our other projects, and it will continue to be an important part of our operations going
There are more features planned and unit tests to write, but we wanted you to see it as soon as possible and have an opportunity to get involved and give feedback. This is what I’m planning to attack in the immediate future:
As more and more people and projects come to use GitHub in their development process, the web hooks
provide an extremely useful, but underused, interface for deploying and sharing work with teammates, clients, and
the public. We hope that
gith can help simplify the process of using them for newcomers and old
hands alike! What else do you want it to do and and how do you plan to use it? Let us know in the