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