# cbrgm/githubevents architecture

> Architecture diagram of the GitHub repository cbrgm/githubevents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cbrgm/githubevents
- Repository: https://github.com/cbrgm/githubevents

## Overview

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: [`githubevents/events.go`](https://github.com/cbrgm/githubevents/blob/main/githubevents/events.go) (Event handler), [`gen/generate.go`](https://github.com/cbrgm/githubevents/blob/main/gen/generate.go) (Generator), [`examples/simple-http-server-packages/main.go`](https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-packages/main.go) (Packages server), [`githubevents/events_issue_comment.go`](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_issue_comment.go) (Issue comment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_library["Library core"]
  node_node_events_go["Event handler<br/>core dispatcher<br/>[events.go]"]
  node_node_events_issue_comment["Issue comment<br/>generated adapter"]
  node_node_events_issues["Issues<br/>generated adapter<br/>[events_issues.go]"]
  node_node_events_pull_request["Pull request<br/>generated adapter"]
  node_node_events_push["Push<br/>generated adapter<br/>[events_push.go]"]
  node_node_events_release["Release<br/>generated adapter<br/>[events_release.go]"]
  node_node_events_workflow_run["Workflow run<br/>generated adapter"]
  node_node_events_installation["Installation<br/>generated adapter"]
  node_node_events_repository["Repository<br/>generated adapter"]
  node_node_events_team["Team<br/>generated adapter<br/>[events_team.go]"]
  node_node_events_misc["Other events<br/>generated adapters<br/>[events_create.go]"]
end

subgraph group_group_codegen["Code generation"]
  node_node_gen_generate["Generator<br/>codegen driver<br/>[generate.go]"]
  node_node_gen_templates["Templates"]
  node_node_gen_params["Params<br/>codegen config<br/>[template_params.go]"]
end

subgraph group_group_examples["Examples"]
  node_node_examples_simple["Simple server<br/>example app<br/>[main.go]"]
  node_node_examples_funcs["Funcs server<br/>example app<br/>[main.go]"]
  node_node_examples_packages["Packages server<br/>example app<br/>[main.go]"]
  node_node_examples_plugin["Responder plugin<br/>example plugin<br/>[responder.go]"]
end

subgraph group_group_external["External deps"]
  node_node_github_events(("GitHub webhooks<br/>external source"))
  node_node_github_types[("go-github types<br/>external model dep")]
end

node_node_github_events -->|"webhook request"| node_node_events_go
node_node_events_go -->|"decode payload"| node_node_github_types
node_node_events_go -->|"dispatch"| node_node_events_issue_comment
node_node_events_go -->|"dispatch"| node_node_events_issues
node_node_events_go -->|"dispatch"| node_node_events_pull_request
node_node_events_go -->|"dispatch"| node_node_events_push
node_node_events_go -->|"dispatch"| node_node_events_release
node_node_events_go -->|"dispatch"| node_node_events_workflow_run
node_node_events_go -->|"dispatch"| node_node_events_installation
node_node_events_go -->|"dispatch"| node_node_events_repository
node_node_events_go -->|"dispatch"| node_node_events_team
node_node_events_go -->|"dispatch"| node_node_events_misc
node_node_events_go -.->|"used by"| node_node_examples_simple
node_node_events_go -.->|"used by"| node_node_examples_funcs
node_node_events_go -.->|"used by"| node_node_examples_packages
node_node_examples_packages -->|"loads"| node_node_examples_plugin
node_node_gen_generate -->|"renders"| node_node_gen_templates
node_node_gen_generate -->|"reads"| node_node_gen_params
node_node_gen_generate -->|"produces"| node_node_events_issue_comment
node_node_gen_generate -->|"produces"| node_node_events_push
node_node_gen_generate -->|"produces"| node_node_events_workflow_run
node_node_gen_generate -->|"produces"| node_node_events_misc

click node_node_events_go "https://github.com/cbrgm/githubevents/blob/main/githubevents/events.go"
click node_node_events_issue_comment "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_issue_comment.go"
click node_node_events_issues "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_issues.go"
click node_node_events_pull_request "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_pull_request.go"
click node_node_events_push "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_push.go"
click node_node_events_release "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_release.go"
click node_node_events_workflow_run "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_workflow_run.go"
click node_node_events_installation "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_installation.go"
click node_node_events_repository "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_repository.go"
click node_node_events_team "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_team.go"
click node_node_events_misc "https://github.com/cbrgm/githubevents/blob/main/githubevents/events_create.go"
click node_node_gen_generate "https://github.com/cbrgm/githubevents/blob/main/gen/generate.go"
click node_node_gen_templates "https://github.com/cbrgm/githubevents/blob/main/gen/template_webhook_event.go.tmpl"
click node_node_gen_params "https://github.com/cbrgm/githubevents/blob/main/gen/template_params.go"
click node_node_examples_simple "https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server/main.go"
click node_node_examples_funcs "https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-funcs/main.go"
click node_node_examples_packages "https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-packages/main.go"
click node_node_examples_plugin "https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-packages/plugins/responder.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_events_go,node_node_events_issue_comment,node_node_events_issues,node_node_events_pull_request,node_node_events_push,node_node_events_release,node_node_events_workflow_run,node_node_events_installation,node_node_events_repository,node_node_events_team,node_node_events_misc toneBlue
class node_node_gen_generate,node_node_gen_templates,node_node_gen_params toneAmber
class node_node_examples_simple,node_node_examples_funcs,node_node_examples_packages,node_node_examples_plugin toneMint
class node_node_github_events,node_node_github_types toneRose
```

## Components

### Library core

Public webhook handling API and generated event adapters.

- [Event handler](https://github.com/cbrgm/githubevents/blob/main/githubevents/events.go): core dispatcher · Central request parsing, event detection, callback registration, and dispatch orchestration. · `githubevents/events.go`
- [Issue comment](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_issue_comment.go): generated adapter · Typed webhook adapter for issue comment events and their callbacks. · `githubevents/events_issue_comment.go`
- [Issues](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_issues.go): generated adapter · Typed webhook adapter for issue events and their callbacks. · `githubevents/events_issues.go`
- [Pull request](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_pull_request.go): generated adapter · Typed webhook adapter for pull request events and their callbacks. · `githubevents/events_pull_request.go`
- [Push](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_push.go): generated adapter · Typed webhook adapter for push events and their callbacks. · `githubevents/events_push.go`
- [Release](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_release.go): generated adapter · Typed webhook adapter for release events and their callbacks. · `githubevents/events_release.go`
- [Workflow run](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_workflow_run.go): generated adapter · Typed webhook adapter for workflow run events and their callbacks. · `githubevents/events_workflow_run.go`
- [Installation](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_installation.go): generated adapter · Typed webhook adapter for GitHub App installation events and their callbacks. · `githubevents/events_installation.go`
- [Repository](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_repository.go): generated adapter · Typed webhook adapter for repository lifecycle events and their callbacks. · `githubevents/events_repository.go`
- [Team](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_team.go): generated adapter · Typed webhook adapter for team events and their callbacks. · `githubevents/events_team.go`
- [Other events](https://github.com/cbrgm/githubevents/blob/main/githubevents/events_create.go): generated adapters · 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](https://github.com/cbrgm/githubevents/blob/main/gen/generate.go): codegen driver · Build-time entrypoint that renders webhook event sources and tests from templates. · `gen/generate.go`
- [Templates](https://github.com/cbrgm/githubevents/blob/main/gen/template_webhook_event.go.tmpl): codegen templates · Source templates for generated webhook event code, tests, and markdown output. · `gen/template_webhook_event.go.tmpl`
- [Params](https://github.com/cbrgm/githubevents/blob/main/gen/template_params.go): codegen config · Template parameter definitions and generation inputs. · `gen/template_params.go`

### Examples

Standalone integration samples showing how consumers embed the library.

- [Simple server](https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server/main.go): example app · Minimal HTTP server example wiring the library into net/http. · `examples/simple-http-server/main.go`
- [Funcs server](https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-funcs/main.go): example app · Function-style example showing direct handler usage. · `examples/simple-http-server-funcs/main.go`
- [Packages server](https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-packages/main.go): example app · Package-based example demonstrating a more modular integration style. · `examples/simple-http-server-packages/main.go`
- [Responder plugin](https://github.com/cbrgm/githubevents/blob/main/examples/simple-http-server-packages/plugins/responder.go): example 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**: external source · Incoming webhook requests and event payloads sent by GitHub.
- **go-github types**: external model dep · Typed GitHub webhook event structs used by the library for decoding and dispatch.

## Connections

- 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.