How cbrgm/githubevents works
1. What this repository is
githubevents is a Go library, not an application service. Its job is to receive GitHub webhook requests, validate/decode them, and fan them out to user-registered callbacks. The main public surface is the githubevents package under githubevents/.
2. Primary runtime flow
The normal path is: GitHub sends a webhook HTTP request → your app calls HandleEventRequest(r) on an EventHandler → the library verifies/parses the payload → it identifies the webhook event and action → it dispatches to the matching callbacks. The library itself does not host the HTTP server; consumer apps wire it into net/http.
3. Core dispatch subsystem
events.go is the central orchestration layer. It likely owns the handler state, secret handling, event detection, request parsing, and callback execution ordering. The README indicates support for per-event callbacks, “any action” callbacks, before/after hooks, and error hooks.
4. Callback model and boundaries
The library exposes several callback tiers:
- event-specific callbacks like OnIssueCommentCreated
- “set” vs “on” registration semantics, where On... appends and SetOn... replaces
- OnBeforeAny and OnAfterAny around every event
- OnError for failures
Callbacks run in parallel within a group, and the handler blocks until a group completes. That concurrency model is important when drawing the architecture.
5. Webhook payload model dependency
The package depends on google/go-github for typed payload structs such as github.IssueCommentEvent. That means the library is primarily a router/adapter around GitHub’s official Go event models rather than a custom payload schema.
6. Generated event surface
Most of the githubevents/events_*.go files are event-specific generated artifacts. Each file maps one GitHub webhook domain object to strongly typed callback registrations and dispatch logic. This is why the repository contains a large number of similarly named files, one per supported webhook type/action family.
7. Code generation pipeline
The gen/ directory is the source-of-truth for generated code. Templates such as template_webhook_event.go.tmpl, template_webhook_event_tests.go.tmpl, and template_markdown.go.tmpl feed gen/generate.go and related helpers. The README and file layout show that new webhook support is added by updating generator parameters, not by hand-editing every event file.
8. Test architecture
Each generated event file has a corresponding test file, for example events_push.go and events_push_test.go. This suggests the repo uses per-event tests to validate parsing, dispatch, and callback wiring. Test coverage is concentrated at the event adapter boundary, where regressions are most likely.
9. Examples as integration references
The examples/ tree contains standalone Go modules demonstrating how to embed the library into a small HTTP server. There are multiple styles: a simple server, a functions-based example, and a packages/plugins example. These examples are not part of the library runtime; they serve as integration documentation and usage patterns.
10. Versioning and compatibility boundary
The README highlights a v2 import path change and a callback signature change that adds context.Context. That means the package boundary is versioned and semantically significant for consumers. The compatibility table also shows the library tracks google/go-github major versions closely, which affects the payload types exposed by the API.
11. Operational shape
There is no database, queue, or external worker system in this repo. The architecture is a synchronous request/dispatch library with optional parallel callback execution. Any persistence, retries, or downstream actions belong to the consuming application, not this repository.
12. How to diagram it
A clear diagram would show:
- External source: GitHub Webhooks
- Consumer app boundary: HTTP server / webhook endpoint
- Library core: EventHandler request validation + event/action routing
- Callback layer: before hooks, event-specific callbacks, after hooks, error hooks
- Model dependency: google/go-github event structs
- Build-time subsystem: generator templates producing the per-event source files
Main entry points: events.go Event handler · generate.go Generator · main.go Packages server · events_issue_comment.go Issue comment
Components 20
Library core
Public webhook handling API and generated event adapters.
- Event handler · Central request parsing, event detection, callback registration, and dispatch orchestration.
githubevents/events.go - Issue comment · Typed webhook adapter for issue comment events and their callbacks.
githubevents/events_issue_comment.go - Issues · Typed webhook adapter for issue events and their callbacks.
githubevents/events_issues.go - Pull request · Typed webhook adapter for pull request events and their callbacks.
githubevents/events_pull_request.go - Push · Typed webhook adapter for push events and their callbacks.
githubevents/events_push.go - Release · Typed webhook adapter for release events and their callbacks.
githubevents/events_release.go - Workflow run · Typed webhook adapter for workflow run events and their callbacks.
githubevents/events_workflow_run.go - Installation · Typed webhook adapter for GitHub App installation events and their callbacks.
githubevents/events_installation.go - Repository · Typed webhook adapter for repository lifecycle events and their callbacks.
githubevents/events_repository.go - Team · Typed webhook adapter for team events and their callbacks.
githubevents/events_team.go - Other events · Representative coverage for the remaining webhook families generated in the package.
githubevents/events_create.go
Code generation
Templates and generator used to produce the event surface.
- Generator · Build-time entrypoint that renders webhook event sources and tests from templates.
gen/generate.go - Templates · Source templates for generated webhook event code, tests, and markdown output.
gen/template_webhook_event.go.tmpl - Params · Template parameter definitions and generation inputs.
gen/template_params.go
Examples
Standalone integration samples showing how consumers embed the library.
- Simple server · Minimal HTTP server example wiring the library into net/http.
examples/simple-http-server/main.go - Funcs server · Function-style example showing direct handler usage.
examples/simple-http-server-funcs/main.go - Packages server · Package-based example demonstrating a more modular integration style.
examples/simple-http-server-packages/main.go - Responder plugin · Example plugin component used by the packages-based sample.
examples/simple-http-server-packages/plugins/responder.go
External deps
Key outside dependencies the library adapts to.
- GitHub webhooks · Incoming webhook requests and event payloads sent by GitHub.
- go-github types · Typed GitHub webhook event structs used by the library for decoding and dispatch.
Connections 22
- GitHub webhooks → Event handler: webhook request · Incoming requests are handed to the event handler API for validation and routing.
- Event handler → go-github types: decode payload · The dispatcher maps webhook payloads onto official typed GitHub event structs.
- Event handler → Issue comment: dispatch · Routes issue comment events to their generated adapter.
- Event handler → Issues: dispatch · Routes issue events to their generated adapter.
- Event handler → Pull request: dispatch · Routes pull request events to their generated adapter.
- Event handler → Push: dispatch · Routes push events to their generated adapter.
- Event handler → Release: dispatch · Routes release events to their generated adapter.
- Event handler → Workflow run: dispatch · Routes workflow run events to their generated adapter.
- Event handler → Installation: dispatch · Routes installation events to their generated adapter.
- Event handler → Repository: dispatch · Routes repository events to their generated adapter.
- Event handler → Team: dispatch · Routes team events to their generated adapter.
- Event handler → Other events: dispatch · Routes the remaining supported webhook families through generated adapters.
- Event handler → Simple server: used by · Consumer applications embed the handler inside a net/http server.
- Event handler → Funcs server: used by · Function-style integration example for the handler API.
- Event handler → Packages server: used by · Package-based integration example for the handler API.
- Packages server → Responder plugin: loads · The packages example composes behavior through a plugin component.
- Generator → Templates: renders · Generator expands templates into the generated webhook source surface.
- Generator → Params: reads · Generation is configured by template parameters.
- Generator → Issue comment: produces · Generated output includes event-specific adapter files.
- Generator → Push: produces · Generated output includes event-specific adapter files.
- Generator → Workflow run: produces · Generated output includes event-specific adapter files.
- Generator → Other events: produces · Generated output includes the rest of the webhook adapter family.