github.com/agrison/harpoon@v0.0.0-20180819075247-a667a15fd0eb/README.md (about) 1 ## Harpoon 2 3 [![Go Report Card](https://goreportcard.com/badge/github.com/agrison/harpoon)][goreportcard] 4 [![Build Status](https://travis-ci.org/agrison/harpoon.svg?branch=master)](https://travis-ci.org/agrison/harpoon) 5 6 [goreportcard]: https://goreportcard.com/report/github.com/agrison/harpoon 7 8 Harpoon is a simple Go program that listens for GitHub hooks like `push` on specific git repository `refs` and execute 9 a defined command when it occurs. 10 11 It can be configured in a TOML configuration file. 12 13 That's nothing fancy, just didn't want to install the whole nodejs + npm or Apache + PHP just for this. 14 15 ### Install 16 17 ```sh 18 go get github.com/agrison/harpoon 19 go build 20 ``` 21 22 Add it to your path if you want. 23 24 ### Runnning 25 26 #### Configuration 27 28 You must have a `config.toml` file located in your directory. 29 30 This is a sample TOML file: 31 32 ```toml 33 port = 9001 34 addr = "0.0.0.0" 35 # tunneling stuff 36 tunnel = true 37 tunnelName = "foobarbazz" 38 39 [events."push:foo/bar:refs/heads/develop"] 40 cmd = "echo" 41 args = "Push!" 42 43 [events."watch:foo/bar:refs/heads/develop"] 44 cmd = "echo" 45 args = "Watch!" 46 ``` 47 48 As you can see events and refs can be configured in the `events` TOML table section. 49 50 These keys have the following format `events.{event}:{repository}:{ref}` where `{event}` refers to a GitHub WebHook event 51 like `push`, `watch`, `pull_request`, ...; `{repository}` is the GitHub repository name and `{ref}` refers to a ref in your git repository like `refs/heads/master` or `refs/tags/v0.0.1`. 52 53 For the above example, it will echo `Push!` when something has been pushed to the `develop` branch of your GitHub repository. 54 It will also echo `Watch!` if someone stars it. 55 56 #### Tunneling 57 58 Tunneling can be enabled using `localtunnel.me`, you just have to enable it in the `config.toml` and indicate a desired subdomain using the `tunnelName` field. 59 If no `tunnelName` is provided then `localtunnel.me` will give you a random subdomain, this subdomain is printed in the console logs. 60 61 #### Really running 62 63 ```sh 64 harpoon 65 ``` 66 67 or to have it verbose (use `-vt` also if you want logs about `localtunnel.me`): 68 ```sh 69 harpoon -v 70 ``` 71 72 It will output something like this when running: 73 ``` 74 __ 75 / /_ ____ __________ ____ ____ ____ 76 / __ \/ __ `/ ___/ __ \/ __ \/ __ \/ __ \ 77 / / / / /_/ / / / /_/ / /_/ / /_/ / / / / 78 /_/ /_/\__,_/_/ / .___/\____/\____/_/ /_/ 79 /_/ 80 Listening on 0.0.0.0:9001 81 82 push detected on foo/bar with ref refs/heads/develop with the following commits: 83 2016-03-08 13:59:38 +0100 CET - adding some awesomeness by Foo Bar 84 2016-03-08 13:59:57 +0100 CET - forgot the unicorn png by Foo Bar 85 2016-03-08 14:01:12 +0100 CET - so much joy in one commit by Foo Bar 86 > Push! 87 ``` 88 89 90 Obviously, the command should be something like `/path/to/pull-build-n-deploy.sh` where some awesome stuff is going on. 91 Like something involving git, maven, rake, npm, bower, I don't know, this is your job :) 92 93 ### Security 94 95 `POST` requests made by GitHub are validated against the `X-Hub-Signature` if the environment variable `GITHUB_HOOK_SECRET_TOKEN` is set. 96 It must be the same as the one defined on the GitHub's WebHook page. 97 98 ### Thanks 99 100 - [https://mholt.github.io/json-to-go/](https://mholt.github.io/json-to-go/) 101 - [https://github.com/BurntSushi/toml](https://github.com/BurntSushi/toml) 102 - [https://github.com/fatih/color](https://github.com/fatih/color) 103 - [https://github.com/gorilla/mux](https://github.com/gorilla/mux) 104 - [https://github.com/NoahShen/gotunnelme](https://github.com/NoahShen/gotunnelme) 105 106 ### Licence 107 MIT