hookserve

Documentation

Overview

HookServe is a small golang utility for receiving github webhooks. It's easy to use, flexible, and provides strong security though GitHub's HMAC webhook verification scheme.

server := hookserve.NewServer()
server.Port = 8888
server.Secret = "supersecretcode"
server.GoListenAndServe()

for {
    select {
    case event := <-server.Events:
        fmt.Println(event.Owner + " " + event.Repo + " " + event.Branch + " " + event.Commit)
    default:
        time.Sleep(100)
    }
}

Command Line Utility

It also comes with a command-line utility that lets you pass webhook push events to other commands

$ hookserve --port=8888 logger -t PushEvent #log github webhook push event to the system log (/var/log/message) via the logger command

Settings up GitHub Webhooks

Setting up webhooks on github is easy. Navigate to `github.com/<name>/<repo>/settings/hooks` and create a new webhook.

Index

• Variables
• type Event
  • func NewEvent(e string) (*Event, error)
  • func (e *Event) String() (output string)
• type Server
  • func NewServer() *Server
  • func (s *Server) GoListenAndServe()
  • func (s *Server) ListenAndServe() error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)

Variables

var ErrInvalidEventFormat = errors.New("Unable to parse event string. Invalid Format.")

Types

type Event

type Event struct {
	Owner      string // The username of the owner of the repository
	Repo       string // The name of the repository
	Branch     string // The branch the event took place on
	Commit     string // The head commit hash attached to the event
	Type       string // Can be either "pull_request" or "push"
	BaseOwner  string // For Pull Requests, contains the base owner
	BaseRepo   string // For Pull Requests, contains the base repo
	BaseBranch string // For Pull Requests, contains the base branch
}

func NewEvent

func NewEvent(e string) (*Event, error)

Create a new event from a string, the string format being the same as the one produced by event.String()

func (*Event) String

func (e *Event) String() (output string)

type Server

type Server struct {
	Address    string     // IP address to listen on. Default to empty string, i.e. all addresses
	Port       string     // Port to listen on. Defaults to 80
	Path       string     // Path to receive on. Defaults to "/postreceive"
	Secret     string     // Option secret key for authenticating via HMAC
	IgnoreTags bool       // If set to false, also execute command if tag is pushed
	Events     chan Event // Channel of events. Read from this channel to get push events as they happen.
}

func NewServer

func NewServer() *Server

Create a new server with sensible defaults. By default the Port is set to 80 and the Path is set to `/postreceive`

func (*Server) GoListenAndServe

func (s *Server) GoListenAndServe()

Inside a go-routine, spin up the server and listen for github webhook push events. The events will be passed to Server.Events channel.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

Spin up the server and listen for github webhook push events. The events will be passed to Server.Events channel.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.Request)

Satisfies the http.Handler interface. Instead of calling Server.ListenAndServe you can integrate hookserve.Server inside your own http server. If you are using hookserve.Server in his way Server.Path should be set to match your mux pattern and Server.Port will be ignored.