feat(webhooks): add flyteplugins-webhooks-github

Receive GitHub webhooks in Flyte. Exports `GitHubProvider`, a Provider subclass with
its defaults pre-wired, so wiring it up reads:

    WebhookAppEnvironment(providers=[GitHubProvider()])

Implements the contract from flyteplugins-webhooks-core: which environment
variable holds the secret, how to verify a delivery, how to parse one into a
WebhookEvent, plus typed constants for every event GitHub can send.

examples/github_webhooks.py runs with no GitHub account at all — `--local` replays
the plugin's own SAMPLE_DELIVERY through the app, so you can watch a delivery
be verified, normalized, and dispatched before wiring anything up.

Runs the shared conformance check, which replays that same sample through
verify and parse rather than trusting them to agree with each other.

Calling the GitHub API is deliberately not this plugin's job.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VKZrTNjjWVzTZUxDFbn4Nk
Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>

Author: cosmicBboy

plugins/webhooks/github/README.md

@@ -0,0 +1,85 @@
+# flyteplugins-webhooks-github
+
+Receive GitHub webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-webhooks-core[app]" flyteplugins-webhooks-github
+```
+
+## Using it
+
+Hand a `GitHubProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyteplugins.webhooks.core import DuplicateRun, WebhookAppEnvironment, idempotent_run
+from flyteplugins.webhooks.github import GitHubProvider, events
+
+app_env = WebhookAppEnvironment(
+    name="github-webhooks",
+    providers=[GitHubProvider()],
+    secrets=[flyte.Secret("GITHUB_WEBHOOK_SECRET", as_env_var="GITHUB_WEBHOOK_SECRET")],
+)
+
+
+@app_env.on_event(events.PullRequest.OPENED)
+async def handle(event):
+    import flyte.remote as remote
+
+    task = remote.Task.get(name="my-env.my_task", auto_version="latest")
+    try:
+        run = await idempotent_run.aio(task, key=event.dedupe_key(), resource=event.resource_id)
+    except DuplicateRun as exc:
+        return {"skipped": str(exc)}
+    return {"run": run.name}
+
+
+flyte.serve(app_env)
+```
+
+Handlers must `await idempotent_run.aio(...)`. The blocking form stalls the
+app's event loop, and GitHub times deliveries out in seconds.
+
+One app can serve several products at once — hand it one provider per product.
+
+## Try it
+
+`examples/github_webhooks.py` runs two ways. The first needs no GitHub account:
+
+```bash
+python examples/github_webhooks.py --local   # replay a real sample delivery in-process
+python examples/github_webhooks.py           # deploy the receiver to Flyte
+```
+
+`--local` posts this plugin's `SAMPLE_DELIVERY` through the app with FastAPI's
+test client, so you see a delivery verified, normalized, and dispatched — plus
+an unsigned one refused with a 401, and the same delivery replayed to show the
+dedupe key is stable.
+
+## Setup
+
+1. Store the secret and mount it on the app:
+   ```bash
+   flyte create secret GITHUB_WEBHOOK_SECRET --value <secret>
+   ```
+2. Point GitHub at `<app-url>/webhook/github`, from
+   repository Settings → Webhooks → Add webhook, content type `application/json`.
+
+GitHub sends a `ping` when the webhook is created; it is answered automatically, so a green check in *Recent Deliveries* means the app is reachable.
+
+**Verification:** HMAC-SHA256 over the raw body (`X-Hub-Signature-256`).
+
+Comment and review events fold the comment id into `resource_id`, so two comments on one issue are two events rather than a redelivery of the first.
+
+## Event constants
+
+`events` spells every event this plugin can dispatch, as `str` enums grouped by
+event type, so a typo fails at import rather than by silently never matching.
+Raw strings still work, for events the constants do not cover yet.
+
+## What this plugin does not do
+
+Call the GitHub API. Use `PyGithub` directly from your tasks — see
+`examples/external_saas_integrations`. This plugin owns only the part that is
+Flyte's: authenticating an inbound delivery and turning it into a run.

plugins/webhooks/github/examples/github_webhooks.py

@@ -0,0 +1,125 @@
+"""Receive GitHub webhooks in Flyte, and see one arrive without leaving your laptop.
+
+Two ways to run this. The second needs no GitHub account at all:
+
+    python github_webhooks.py --local   # replay a real sample delivery in-process
+    python github_webhooks.py           # deploy the receiver to Flyte
+
+`--local` runs the app through FastAPI's test client and posts this plugin's
+`SAMPLE_DELIVERY` — a `pull_request.opened` delivery — signed with a throwaway secret. You see the
+delivery verified, normalized, and dispatched to a handler, which is the whole
+path a real webhook takes.
+
+To receive real events, deploy it and point GitHub at `<app-url>/webhook/github`
+from repository Settings -> Webhooks -> Add webhook, content type `application/json`.
+
+Setup for the real thing:
+    flyte create secret GITHUB_WEBHOOK_SECRET --value <secret>
+
+A fine-grained token is not needed to *receive* webhooks — only the shared secret you set on the webhook itself.
+"""
+
+import os
+import sys
+
+import flyte
+from flyteplugins.webhooks.core import WebhookAppEnvironment
+
+from flyteplugins.webhooks.github import DEFAULT_SECRET_ENV, SAMPLE_DELIVERY, GitHubProvider, events
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages(
+    "flyteplugins-webhooks-core[app]", "flyteplugins-webhooks-github"
+)
+
+app_env = WebhookAppEnvironment(
+    name="github-webhooks",
+    providers=[GitHubProvider()],
+    image=image,
+    secrets=[flyte.Secret(DEFAULT_SECRET_ENV, as_env_var=DEFAULT_SECRET_ENV)],
+)
+
+
+@app_env.on_event(events.PullRequest.OPENED)
+async def on_primary(event):
+    """React to the event this plugin's sample delivery carries.
+
+    Returning a dict is enough to see the path working. To do real work, launch
+    a deployed task instead — see `launch_a_task` below.
+    """
+    return {
+        "saw": event.qualified_type,
+        "resource": event.resource_id,
+        "title": event.title,
+        # The key `idempotent_run` would dedupe on. Replaying the same delivery
+        # produces the same key, which is what makes a redelivery a no-op.
+        "dedupe_key": event.dedupe_key(),
+    }
+
+
+@app_env.on_event(events.Issues.OPENED)
+async def on_secondary(event):
+    """A second handler, to show dispatch picking the right one per event."""
+    return {"saw": event.qualified_type, "resource": event.resource_id}
+
+
+async def launch_a_task(event):
+    """What a handler looks like once it does real work.
+
+    Not registered above, because it needs `github-triage.triage_pr` deployed first
+    and a Flyte backend to launch into. Wire it up with:
+
+        @app_env.on_event(events.PullRequest.OPENED)
+
+    `idempotent_run` refuses to launch when a run carrying the same dedupe key
+    is already live or has succeeded, so GitHub redelivering an event — which
+    it does on any non-2xx — never starts a second run.
+    """
+    import flyte.remote as remote
+    from flyteplugins.webhooks.core import DuplicateRun, idempotent_run
+
+    task = remote.Task.get(name="github-triage.triage_pr", auto_version="latest")
+    try:
+        # Always `.aio`: the blocking form stalls the app's event loop, and
+        # webhook senders time deliveries out in seconds.
+        run = await idempotent_run.aio(
+            task, key=event.dedupe_key(), repo=event.scope, number=int((event.resource_id or "#0").split("#")[1])
+        )
+    except DuplicateRun as exc:
+        return {"skipped": str(exc)}
+    return {"run": run.name}
+
+
+def _try_locally() -> None:
+    """Post this plugin's sample delivery to the app, in-process."""
+    from fastapi.testclient import TestClient
+
+    secret = os.environ.setdefault(DEFAULT_SECRET_ENV, "local-trial-secret")
+    build_headers, body = SAMPLE_DELIVERY
+    client = TestClient(app_env.app)
+
+    print("POST /webhook/github  (signed with a throwaway secret)")
+    response = client.post("/webhook/github", content=body, headers=build_headers(body, secret))
+    print(f"  {response.status_code}  {response.json()}\n")
+
+    print("the same delivery again — note the identical dedupe_key:")
+    again = client.post("/webhook/github", content=body, headers=build_headers(body, secret))
+    print(f"  {again.status_code}  {again.json()}\n")
+
+    print("an unsigned delivery is refused:")
+    bad = client.post("/webhook/github", content=body, headers={})
+    print(f"  {bad.status_code}  {bad.json()}\n")
+
+    print("normalized events the app has seen:")
+    for seen in client.get("/api/events").json():
+        print(f"  {seen['provider']}  {seen['qualified_type']}  resource={seen['resource_id']}")
+
+
+if __name__ == "__main__":
+    if "--local" in sys.argv:
+        _try_locally()
+    else:
+        flyte.init_from_config()
+        handle = flyte.serve(app_env)
+        handle.activate(wait=True)
+        print(f"Dashboard ready at {handle.endpoint}")
+        print(f"Point GitHub at {handle.endpoint}/webhook/github")

plugins/webhooks/github/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "flyteplugins-webhooks-github"
+dynamic = ["version"]
+description = "Receive GitHub webhooks in Flyte."
+readme = "README.md"
+authors = [{ name = "Flyte Contributors" }]
+requires-python = ">=3.10"
+dependencies = ["flyteplugins-webhooks-core"]
+
+[build-system]
+requires = ["setuptools", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "httpx>=0.27",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["flyteplugins*"]
+
+[tool.setuptools_scm]
+root = "../../.."
+
+[tool.pytest.ini_options]
+norecursedirs = []
+log_cli = true
+log_cli_level = 20
+markers = []
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+branch = true
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "PLW", "YTT", "ASYNC", "C4", "T10", "EXE", "ISC", "LOG", "PIE", "Q", "RSE", "FLY", "PGH", "PLC", "PLE", "FURB", "RUF"]
+ignore = ["PGH003", "PLC0415"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/*" = ["E402"]
+
+[tool.uv.sources]
+flyte = { path = "../../..", editable = true }
+flyteplugins-webhooks-core = { path = "../core", editable = true }

plugins/webhooks/github/src/flyteplugins/webhooks/github/__init__.py

@@ -0,0 +1,63 @@
+"""GitHub webhooks for Flyte.
+
+Hand a `GitHubProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyteplugins.webhooks.core import DuplicateRun, WebhookAppEnvironment, idempotent_run
+from flyteplugins.webhooks.github import GitHubProvider, events
+
+app_env = WebhookAppEnvironment(
+    name="github-webhooks",
+    providers=[GitHubProvider()],
+    secrets=[flyte.Secret("GITHUB_WEBHOOK_SECRET", as_env_var="GITHUB_WEBHOOK_SECRET")],
+)
+
+
+@app_env.on_event(events.PullRequest.OPENED)
+async def triage(event):
+    import flyte.remote as remote
+
+    task = remote.Task.get(name="github-triage.triage_pr", auto_version="latest")
+    try:
+        run = await idempotent_run.aio(task, key=event.dedupe_key(), repo=event.scope)
+    except DuplicateRun as exc:
+        return {"skipped": str(exc)}
+    return {"run": run.name}
+```
+
+Calling the GitHub API is not this plugin's job — use `PyGithub` from your
+tasks. See `examples/external_saas_integrations`.
+"""
+
+import hashlib
+import hmac
+
+from . import events
+from ._provider import DEFAULT_SECRET_ENV, GitHubProvider, handshake, parse, verify
+
+__all__ = ["DEFAULT_SECRET_ENV", "SAMPLE_DELIVERY", "GitHubProvider", "events", "handshake", "parse", "verify"]
+
+
+def _sample_headers(body: bytes, secret: str) -> dict[str, str]:
+    signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    return {
+        "X-GitHub-Event": "pull_request",
+        "X-GitHub-Delivery": "00000000-0000-0000-0000-000000000000",
+        "X-Hub-Signature-256": f"sha256={signature}",
+    }
+
+
+#: A real `pull_request.opened` delivery, trimmed to the fields the parser reads.
+#: The conformance harness signs and replays it, so `verify` and `parse` are
+#: checked against an actual payload rather than against each other.
+SAMPLE_DELIVERY = (
+    _sample_headers,
+    (
+        b'{"action": "opened", "number": 7,'
+        b' "pull_request": {"number": 7, "title": "Add a feature",'
+        b' "html_url": "https://github.com/octo/repo/pull/7", "updated_at": "2024-01-01T00:00:00Z"},'
+        b' "repository": {"full_name": "octo/repo"}, "sender": {"login": "octocat"}}'
+    ),
+)