githubwebhook

Documentation

Overview

Package githubwebhook provides an HTTP input component that receives GitHub webhook events and publishes them to NATS JetStream.

Index

• func CreateInput(rawConfig json.RawMessage, deps component.Dependencies) (component.Discoverable, error)
• func Register(registry *component.Registry) error
• type CommentEvent
• type CommentPayload
• type Config
  • func DefaultConfig() Config
• type Input
  • func NewInput(name string, natsClient *natsclient.Client, cfg Config, logger *slog.Logger) (*Input, error)
  • func (i *Input) ConfigSchema() component.ConfigSchema
  • func (i *Input) DataFlow() component.FlowMetrics
  • func (i *Input) Health() component.HealthStatus
  • func (i *Input) Initialize() error
  • func (i *Input) InputPorts() []component.Port
  • func (i *Input) Meta() component.Metadata
  • func (i *Input) OutputPorts() []component.Port
  • func (i *Input) Start(ctx context.Context) error
  • func (i *Input) Stop(timeout time.Duration) error
• type IssueEvent
• type IssuePayload
• type PREvent
• type PRPayload
• type Repository
• type ReviewEvent
• type ReviewPayload
• type WebhookEvent

Functions

func CreateInput

func CreateInput(rawConfig json.RawMessage, deps component.Dependencies) (component.Discoverable, error)

CreateInput is the factory function for creating GitHub webhook input components. It follows the standard component factory signature so that it can be registered with the component registry.

func Register

func Register(registry *component.Registry) error

Register registers the GitHub webhook input component with the supplied registry.

Types

type CommentEvent

type CommentEvent struct {
	WebhookEvent
	Comment CommentPayload `json:"comment"`
}

CommentEvent represents a GitHub "issue_comment" webhook event.

type CommentPayload

type CommentPayload struct {
	// Body is the comment text.
	Body string `json:"body"`

	// Author is the GitHub login of the comment author.
	Author string `json:"author"`
}

CommentPayload contains the fields extracted from a GitHub issue comment.

type Config

type Config struct {
	// HTTPPort is the port the webhook HTTP server listens on.
	HTTPPort int `json:"http_port" schema:"type:int,description:HTTP port for webhook receiver,default:8090,category:basic"`

	// Path is the URL path that receives GitHub webhook POST requests.
	Path string `json:"path" schema:"type:string,description:Webhook endpoint path,default:/github/webhook,category:basic"`

	// WebhookSecretEnv is the name of the environment variable that holds
	// the HMAC secret used to validate X-Hub-Signature-256 signatures.
	// When empty, signature validation is skipped (not recommended for production).
	WebhookSecretEnv string `` /* 133-byte string literal not displayed */

	// RepoAllowlist restricts processing to specific repositories in
	// "owner/repo" format. An empty slice accepts events from all repositories.
	RepoAllowlist []string `json:"repo_allowlist" schema:"type:array,description:Repositories to process (owner/repo format),category:basic"`

	// EventFilter restricts which GitHub event types are accepted.
	// Valid values: issues, pull_request, pull_request_review, issue_comment.
	// An empty slice falls back to the package defaults.
	EventFilter []string `` /* 151-byte string literal not displayed */

	// Ports configures the output NATS subjects for each event category.
	Ports *component.PortConfig `json:"ports,omitempty" schema:"type:ports,description:Port configuration,category:basic"`
}

Config holds configuration for the GitHub webhook input component.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config populated with sensible defaults.

type Input

type Input struct {
	// contains filtered or unexported fields
}

Input implements the GitHub webhook HTTP receiver component.

func NewInput

func NewInput(name string, natsClient *natsclient.Client, cfg Config, logger *slog.Logger) (*Input, error)

NewInput creates a validated Input from the supplied configuration and NATS client.

func (*Input) ConfigSchema

func (i *Input) ConfigSchema() component.ConfigSchema

ConfigSchema returns the configuration schema.

func (*Input) DataFlow

func (i *Input) DataFlow() component.FlowMetrics

DataFlow returns current throughput metrics.

func (*Input) Health

func (i *Input) Health() component.HealthStatus

Health returns the current health status.

func (*Input) Initialize

func (i *Input) Initialize() error

Initialize validates the configuration and pre-loads the webhook HMAC secret from the environment so that secret retrieval failures surface early.

func (*Input) InputPorts

func (i *Input) InputPorts() []component.Port

InputPorts returns the input ports. The HTTP listener is the entry point, represented as a NetworkPort.

func (*Input) Meta

func (i *Input) Meta() component.Metadata

Meta returns component metadata.

func (*Input) OutputPorts

func (i *Input) OutputPorts() []component.Port

OutputPorts returns the four JetStream output ports, one per event category.

func (*Input) Start

func (i *Input) Start(ctx context.Context) error

Start launches the HTTP server and begins accepting webhook deliveries.

func (*Input) Stop

func (i *Input) Stop(timeout time.Duration) error

Stop performs a graceful HTTP server shutdown within the supplied timeout.

type IssueEvent

type IssueEvent struct {
	WebhookEvent
	Issue IssuePayload `json:"issue"`
}

IssueEvent represents a GitHub "issues" webhook event.

type IssuePayload

type IssuePayload struct {
	// Number is the repository-scoped issue number.
	Number int `json:"number"`

	// Title is the issue title.
	Title string `json:"title"`

	// Body is the issue body text (may be empty).
	Body string `json:"body"`

	// State is the issue state: "open" or "closed".
	State string `json:"state"`

	// Labels is the list of label names applied to the issue.
	Labels []string `json:"labels"`

	// Author is the GitHub login of the issue author.
	Author string `json:"author"`

	// HTMLURL is the canonical browser URL for the issue.
	HTMLURL string `json:"html_url"`
}

IssuePayload contains the fields extracted from a GitHub issue object.

type PREvent

type PREvent struct {
	WebhookEvent
	PullRequest PRPayload `json:"pull_request"`
}

PREvent represents a GitHub "pull_request" webhook event.

type PRPayload

type PRPayload struct {
	// Number is the repository-scoped pull-request number.
	Number int `json:"number"`

	// Title is the pull-request title.
	Title string `json:"title"`

	// Body is the pull-request description (may be empty).
	Body string `json:"body"`

	// State is the PR state: "open", "closed", or "merged".
	State string `json:"state"`

	// Head is the name of the source branch.
	Head string `json:"head"`

	// Base is the name of the target branch.
	Base string `json:"base"`

	// HTMLURL is the canonical browser URL for the pull request.
	HTMLURL string `json:"html_url"`
}

PRPayload contains the fields extracted from a GitHub pull-request object.

type Repository

type Repository struct {
	// Owner is the organisation or user that owns the repository.
	Owner string `json:"owner"`

	// Name is the repository name without the owner prefix.
	Name string `json:"name"`

	// FullName is the canonical "owner/name" identifier.
	FullName string `json:"full_name"`
}

Repository holds the identifying fields of a GitHub repository.

type ReviewEvent

type ReviewEvent struct {
	WebhookEvent
	Review      ReviewPayload `json:"review"`
	PullRequest PRPayload     `json:"pull_request"`
}

ReviewEvent represents a GitHub "pull_request_review" webhook event.

type ReviewPayload

type ReviewPayload struct {
	// State is the review outcome: "approved", "changes_requested", or "commented".
	State string `json:"state"`

	// Body is the review summary comment (may be empty).
	Body string `json:"body"`
}

ReviewPayload contains the fields extracted from a GitHub pull-request review.

type WebhookEvent

type WebhookEvent struct {
	// EventType is the value of the X-GitHub-Event header (e.g. "issues").
	EventType string `json:"event_type"`

	// Action is the fine-grained sub-action within the event type
	// (e.g. "opened", "edited", "closed").
	Action string `json:"action"`

	// Repository identifies the repository that generated the event.
	Repository Repository `json:"repository"`

	// Sender is the GitHub login of the user who triggered the event.
	Sender string `json:"sender"`

	// ReceivedAt is the UTC timestamp at which this process received the event.
	ReceivedAt time.Time `json:"received_at"`
}

WebhookEvent is the common header present in every GitHub webhook event. Specific event types embed this struct and add their own domain-specific fields.