README
¶
githubevents
GitHub webhook events toolset for Go
githubevents is a webhook events toolset for the Go programming language inspired by octokit/webhooks.js.
This library makes use of google/go-github and provides functionality to register callbacks for Github events and their actions, so that you can easily execute your own logic in response to webhook events.
Usage
import (
"github.com/cbrgm/githubevents/githubevents"
)
Create a new githubevents.EventHandler, register callbacks and start a http server.
package main
import (
"fmt"
"github.com/cbrgm/githubevents/githubevents"
"github.com/google/go-github/v50/github"
"net/http"
)
func main() {
// create a new event handler
handle := githubevents.New("secretkey")
// add callbacks
handle.OnIssueCommentCreated(
func(deliveryID string, eventName string, event *github.IssueCommentEvent) error {
fmt.Printf("%s made a comment!", event.Sender.Login)
return nil
},
)
// add a http handleFunc
http.HandleFunc("/hook", func(w http.ResponseWriter, r *http.Request) {
err := handle.HandleEventRequest(r)
if err != nil {
fmt.Println("error")
}
})
// start the server listening on port 8080
if err := http.ListenAndServe(":8080", nil); err != nil {
panic(err)
}
}
For more usage examples, please have a look at the examples directory.
API
Please refer to pkg.go.dev for a full list of supported callback functions.
Constructor
To create a new githubevents.EventHandler use the following constructor:
handle := githubevents.New("secretkey")
// ...
secretkey is the GitHub Webhook secret token. If your webhook does not contain a secret token, you can set nil.
This is intended for local development purposes only and all webhooks should ideally set up a secret token.
Callbacks
Functions to register callbacks follow a specific naming scheme. On... functions register one or more callbacks and add them to previously registered ones.
SetOn... functions also register callbacks, but override previously registered ones.
On...Any/SetOn...Any functions register callbacks that are executed on each action of an event (if the event has actions).
A full list of supported events for this Go module can be found under the section "Supported Webhooks Events". A full documentation including all functions to register callbacks can be found on pkg.go.dev.
Callback Execution Order
Each callback in a registered group is executed in parallel. Each group blocks until all callbacks executed in parallel have returned,
then returns the first non-nil error (if any) from them. If OnError callbacks have been set, they will be called when an error occurs.
The order of execution is open for discussion, contributions are welcome!
OnBeforeAny
OnBeforeAny registers callbacks which are triggered before any event. Registered callbacks are executed in parallel in separate Goroutines.
handle := githubevents.New("secretkey")
handle.OnBeforeAny(
func(deliveryID string, eventName string, event interface{}) error {
fmt.Printf("%s event received!", eventName)
// do something
return nil
},
)
// ...
OnAfterAny
OnAfterAny registers callbacks which are triggered after any event. Registered callbacks are executed in parallel in separate Goroutines.
handle := githubevents.New("secretkey")
handle.OnAfterAny(
func(deliveryID string, eventName string, event interface{}) error {
fmt.Printf("%s event received!", eventName)
// do something
return nil
},
)
// ...
OnError
OnError registers callbacks which are triggered whenever an error occurs. These callbacks can be used for additional error handling, debugging or logging purposes. Registered callbacks are executed in parallel in separate Goroutines.
handle := githubevents.New("secretkey")
handle.OnError(
func(deliveryID string, eventName string, event interface{}, err error) error {
fmt.Printf("received error %s", err)
// additional error handling ...
return err
},
)
// ...
Supported Webhooks Events
Local development
All Go code in githubevents is generated via the make target make generate (Go 1.18+ required).
Changes must be done in gen/generate.go. To add new events, add a corresponding entry to gen/template_params.go.
To validate the generated go code run go run examples/simple-http-server and make changes to test your functions.
You can use services like ngrok to expose your local port 8080 to the world.
Enter the public domain name as the webhook endpoint. You can install webhooks on an organization or on a specific repository.
To set up a webhook, go to the settings page of your repository or organization. From there, click Webhooks, then Add webhook.
Alternatively, you can choose to build and manage a webhook through the Webhooks API.
Compatibility
| google/go-github | cbrgm/githubevents |
|---|---|
v50.x |
v1.8.x |
v49.x |
<= v1.7.x |
v48.x |
<=v1.6.x |
v47.x |
<=v1.4.x |
v46.x |
<=v1.3.x |
v45.x |
<=v1.2.x |
v44.x |
<=v1.1.2x |
v43.x |
<=v1.1.1x |
Contributing & License
Feel free to submit changes! See the Contributing Guide. This project is open-source and is developed under the terms of the MIT License.
Directories