feat: add webhook support for GitHub events (AIE-13)

[tmarshall]

What type of PR is this?

/kind feature

What this PR does / why we need it:

Adds webhook support for GitHub events to Kelos. TaskSpawners can now receive push notifications when issues or pull requests are created or updated, providing an alternative to API polling.

Which issue(s) this PR is related to:

Related to kelos-dev#687 (upstream Kelos webhook support request)

Linear ticket: AIE-13

Special notes for your reviewer:

Architecture: CRD-Based Queue

Webhook payloads are stored as WebhookEvent custom resources in Kubernetes. This is consistent with Kelos' existing architecture where all state lives in Kubernetes CRDs backed by etcd.

Alternative approaches considered:

• In-memory queue with ConfigMap snapshots: Faster but loses events on crash between snapshots
• External queue (Redis/RabbitMQ): Adds infrastructure dependency and is not Kubernetes-native

The CRD-based approach provides:

• Persistence across pod restarts (etcd-backed)
• Visibility via kubectl (kubectl get webhookevents)
• Built-in RBAC and audit logging
• Consistency with existing Kelos patterns

---

Components:

1. WebhookEvent CRD (api/v1alpha1/webhookevent_types.go)

   • Custom resource for storing webhook payloads
   • Spec: source, payload, receivedAt
   • Status: processed flag, processedAt timestamp

2. Webhook Receiver (cmd/kelos-webhook-receiver/main.go)

   • HTTP server listening on /webhook/github
   • Validates GitHub webhook signatures (HMAC-SHA256)
   • Creates WebhookEvent CRD instances
   • Returns 202 Accepted

3. GitHub Webhook Source (internal/source/github_webhook.go)

   • Implements Source interface
   • Lists unprocessed WebhookEvent resources with source=github
   • Parses GitHub issue and pull_request payloads
   • Converts to WorkItem format
   • Marks events as processed
   • Supports label-based filtering (client-side)

4. TaskSpawner CRD Updates (api/v1alpha1/taskspawner_types.go)

   • Adds githubWebhook field to When struct

5. Unit Tests

   • Webhook receiver: signature validation, HTTP handling
   • GitHub webhook source: payload parsing, label filtering, discovery flow

6. Documentation & Examples

   • docs/webhooks.md: Architecture overview and setup instructions
   • examples/taskspawner-github-webhook.yaml: Complete example with receiver deployment

---

Usage example:

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: my-webhook-spawner
spec:
  when:
    githubWebhook:
      namespace: default
      labels: ["kelos-task"]
      excludeLabels: ["skip"]
  taskTemplate:
    type: claude-code
    credentials:
      type: api-key
      secretRef:
        name: anthropic-api-key
    workspaceRef:
      name: my-workspace

---

Compatibility with main:

This implementation is compatible with the upstream main branch:

• No changes to existing API polling sources
• Webhook support is opt-in via githubWebhook field
• No breaking changes to existing TaskSpawner specs

---

TODO before merging:

• Run make update in Go environment to generate:
  • Deep copy code (zz_generated.deepcopy.go)
  • CRD manifests
• Add unit tests for webhook receiver signature validation
• Add unit tests for GitHub webhook source payload parsing
• Add RBAC permissions for WebhookEvent resources
• Add integration test for end-to-end flow (requires live cluster)
• Test in development cluster

Does this PR introduce a user-facing change?

Adds webhook support for GitHub events. TaskSpawners can now use `when.githubWebhook` to receive push notifications for issues and pull requests. Requires deploying the new `kelos-webhook-receiver` component. See `docs/webhooks.md` for setup instructions.

[knechtionscoding]

Overall I think this is fine. Might need to think through the routing part of it (i.e. different ingresses pointing at different services)?

We may also want the taskspawner, if it is a webhook source, to create the service with specific overrides to allow for clusterIP vs load balancer, annotations and labels, etc.