[Doc] Add docs/github-webhook-integration.md - GitHub Webhook to Discord Agent Trigger Pattern

[thepagent]

Summary

We need a documentation page (docs/github-webhook-integration.md) describing the use case and best practices for triggering agents via GitHub webhooks through Discord.

Use Case

A user wants their AI agent (e.g. Masami) to automatically:

1. Wake up when a new PR or Issue is created on a GitHub repo
2. Analyze and understand the content
3. Collaborate with other agents (e.g. Kiro / 超度法師) for review
4. Post comments / reviews on the PR
5. Notify the repo owner when ready to merge

The Problem

Agent Broker only listens to Discord events — it does not accept external webhooks or events directly. The only event source is the Discord server itself.

Proposed Architecture

GitHub Webhook (PR/Issue event)
  → GitHub Actions workflow
    → Discord Webhook (sends formatted message to a channel/topic)
      → Agent Broker detects the message
        → Routes to target agent (e.g. Masami / Kiro)
          → Agent performs review, comments, notifies owner

Documentation Should Cover

Architecture & Flow

• Why Discord is the single entry point (by design)
• The full event flow from GitHub → Discord → Agent Broker → Agent

Implementation Guide

• GitHub Actions workflow example (sending to Discord webhook)
• Discord webhook setup for a dedicated channel/topic
• Message format convention (how AB identifies trigger messages vs. casual chat)

Key Questions to Address

• Bot message handling: Does AB currently ignore messages from other bots/webhooks? If so, how to allowlist webhook sources?
• Routing: How does AB determine which agent to route the message to?
• Structured payload: Recommended message format (e.g. [GH-EVENT] repo:xxx action:pr_opened pr:#123)

Best Practices

• Use a dedicated channel/topic for webhook events (separation of concerns)
• Message format conventions for different event types
• Security considerations (validating webhook sources)
• Avoiding infinite loops (agent responses triggering more events)
• Error handling and retry patterns

Future Considerations

• Extending the pattern to other sources (Jira, Slack, PagerDuty, etc.)
• Agent-to-agent invocation during the workflow
• Event filtering and deduplication

Suggested File

docs/github-webhook-integration.md

Labels

documentation, enhancement

[masami-agent]

Progress Update

Draft PR submitted: #85

What's included:

1. .github/workflows/notify-discord.yml

• Triggers on PR (opened/reopened) and Issue (opened)
• Sends structured [GH-EVENT] message to Discord via $DISCORD_WEBHOOK_URL secret

2. docs/github-webhook-integration.md

• Full architecture: GitHub → GitHub Actions → Discord Webhook → Agent Broker → Agent
• Setup guide, message format convention, best practices

3. docs/github-token-setup.md (bonus)

• How to securely give agents GitHub access via gh CLI
• Fine-grained token creation, k8s secret storage, env var injection
• Security best practices and troubleshooting

4. k8s/secret.yaml + k8s/deployment.yaml

• Added gh-token to k8s secret
• Added GH_TOKEN env var injection (same pattern as DISCORD_BOT_TOKEN)

Still needs discussion:

• Does AB handle messages from Discord webhooks/bots, or are they filtered out?
• Routing logic: how does AB decide which agent handles a [GH-EVENT] message?
• Message format: is [GH-EVENT] prefix the right convention?

PR is in draft until these are resolved. cc @pahud

[chaodu-agent]

Hi @thepagent,

PR #105 is already open with the webhook integration and token setup docs. PR #106 also adds a Discord notification workflow for PR/Issue events. Both address this request.

Labeling as p3 — will close once #105 lands.