feat(jira): add flyteplugins-jira

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

    WebhookAppEnvironment(providers=[JiraProvider()])

The receiver itself ships with flyte, at flyte.extras.webhooks; this package
contributes only what is specific to Jira -- which environment variable holds
the secret, how to verify a delivery, how to parse one into a WebhookEvent, and
typed constants for every event Jira sends.

examples/jira_webhooks.py runs with no Jira account at all: --local replays
this plugin's own SAMPLE_DELIVERY through the app, so you can watch a delivery
be verified, normalized, and dispatched before wiring anything up. The shared
conformance check exercises that same sample.

The package is named for the product rather than for webhooks, so client
methods can land here later when they earn their place -- returning
flyte.io.File instead of an inline megabyte payload, rendering into the task
report, or participating in caching and fan-out. Plain API passthrough belongs
in the vendor's own SDK, called directly from a task.

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/jira/README.md

@@ -0,0 +1,83 @@
+# flyteplugins-jira
+
+Receive Jira webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-jira[app]"
+```
+
+## Using it
+
+Hand a `JiraProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyte.extras.webhooks import DuplicateRun, WebhookAppEnvironment, idempotent_run
+from flyteplugins.jira import JiraProvider, events
+
+app_env = WebhookAppEnvironment(
+    name="jira-webhooks",
+    providers=[JiraProvider()],
+    secrets=[flyte.Secret("JIRA_WEBHOOK_TOKEN", as_env_var="JIRA_WEBHOOK_TOKEN")],
+)
+
+
+@app_env.on_event(events.Issue.CREATED)
+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 Jira times deliveries out in seconds.
+
+One app can serve several products at once — hand it one provider per product.
+
+## Try it
+
+`examples/jira_webhooks.py` runs two ways. The first needs no Jira account:
+
+```bash
+python examples/jira_webhooks.py --local   # replay a real sample delivery in-process
+python examples/jira_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 JIRA_WEBHOOK_TOKEN --value <secret>
+   ```
+2. Point Jira at `<app-url>/webhook/jira`, from
+   Jira Settings → System → Webhooks.
+
+**Verification:** **None.** Jira Cloud does not sign its webhooks.
+
+Because there is no signature, this plugin authenticates with a shared token in `X-Webhook-Token` — which something in front of the app has to inject, since Jira cannot send custom headers. `JiraProvider` reports `signed=False`, so the dashboard says the product does not sign rather than implying a guarantee that is absent. A shared token also cannot detect body tampering, only that the sender knew the token.
+
+## 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 Jira API. Use the `jira` package 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/jira/examples/jira_webhooks.py

@@ -0,0 +1,123 @@
+"""Receive Jira webhooks in Flyte, and see one arrive without leaving your laptop.
+
+Two ways to run this. The second needs no Jira account at all:
+
+    python jira_webhooks.py --local   # replay a real sample delivery in-process
+    python jira_webhooks.py           # deploy the receiver to Flyte
+
+`--local` runs the app through FastAPI's test client and posts this plugin's
+`SAMPLE_DELIVERY` — a `jira:issue_created` 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 Jira at `<app-url>/webhook/jira`
+from Jira Settings -> System -> Webhooks.
+
+Setup for the real thing:
+    flyte create secret JIRA_WEBHOOK_TOKEN --value <secret>
+
+Jira does not sign webhooks, so this is a token you invent. Something in front
+of the app has to inject it as `X-Webhook-Token`, since Jira cannot send custom
+headers itself.
+"""
+
+import os
+import sys
+
+import flyte
+from flyte.extras.webhooks import WebhookAppEnvironment
+
+from flyteplugins.jira import DEFAULT_SECRET_ENV, SAMPLE_DELIVERY, JiraProvider, events
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("flyteplugins-jira[app]")
+
+app_env = WebhookAppEnvironment(
+    name="jira-webhooks",
+    providers=[JiraProvider()],
+    image=image,
+    secrets=[flyte.Secret(DEFAULT_SECRET_ENV, as_env_var=DEFAULT_SECRET_ENV)],
+)
+
+
+@app_env.on_event(events.Issue.CREATED)
+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.Comment.CREATED)
+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 `jira-tickets.triage_issue` deployed first
+    and a Flyte backend to launch into. Wire it up with:
+
+        @app_env.on_event(events.Issue.CREATED)
+
+    `idempotent_run` refuses to launch when a run carrying the same dedupe key
+    is already live or has succeeded, so Jira redelivering an event — which
+    it does on any non-2xx — never starts a second run.
+    """
+    import flyte.remote as remote
+    from flyte.extras.webhooks import DuplicateRun, idempotent_run
+
+    task = remote.Task.get(name="jira-tickets.triage_issue", 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(), issue_key=event.resource_id)
+    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/jira  (signed with a throwaway secret)")
+    response = client.post("/webhook/jira", 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/jira", 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/jira", 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 Jira at {handle.endpoint}/webhook/jira")

plugins/jira/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "flyteplugins-jira"
+dynamic = ["version"]
+description = "Receive Jira webhooks in Flyte."
+readme = "README.md"
+authors = [{ name = "Flyte Contributors" }]
+requires-python = ">=3.10"
+# The webhook receiver lives in flyte itself, at flyte.extras.webhooks.
+dependencies = ["flyte"]
+
+[project.optional-dependencies]
+app = ["fastapi>=0.115", "uvicorn>=0.30"]
+
+[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 }

plugins/jira/src/flyteplugins/jira/__init__.py

@@ -0,0 +1,31 @@
+"""Jira webhooks for Flyte.
+
+Hand a `JiraProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`. Calling the Jira API is not this plugin's job — use
+the `jira` package from your tasks. See `examples/external_saas_integrations`.
+
+Note Jira does not sign its webhooks; see `_provider` for what this plugin does
+instead.
+"""
+
+from . import events
+from ._provider import DEFAULT_SECRET_ENV, JiraProvider, parse, verify
+
+__all__ = ["DEFAULT_SECRET_ENV", "SAMPLE_DELIVERY", "JiraProvider", "events", "parse", "verify"]
+
+
+def _sample_headers(body: bytes, secret: str) -> dict[str, str]:
+    # No signature to compute: Jira sends a static shared token.
+    return {"X-Webhook-Token": secret}
+
+
+#: A real `jira:issue_created` delivery, trimmed to the fields the parser reads.
+SAMPLE_DELIVERY = (
+    _sample_headers,
+    (
+        b'{"webhookEvent": "jira:issue_created", "timestamp": 1700000000000,'
+        b' "user": {"displayName": "Bob"},'
+        b' "issue": {"key": "PROJ-1", "id": "10001",'
+        b' "fields": {"summary": "A bug", "project": {"key": "PROJ"}}}}'
+    ),
+)

plugins/jira/src/flyteplugins/jira/_provider.py

@@ -0,0 +1,81 @@
+"""Jira webhook verification and payload normalization.
+
+Jira Cloud does **not** sign its webhooks. There is no HMAC to check, so this
+plugin authenticates with a shared token in `X-Webhook-Token` — which something
+in front of the app has to inject, because Jira itself cannot send custom
+headers. `JiraProvider` reports `signed=False` so the dashboard says so plainly rather than
+implying a guarantee that is not there.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from flyte.extras.webhooks import (
+    Provider,
+    WebhookEvent,
+    constant_time_equals,
+    json_body,
+    lower_headers,
+)
+
+#: Environment variable this provider reads its secret from by default.
+DEFAULT_SECRET_ENV = "JIRA_WEBHOOK_TOKEN"
+
+
+def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool:
+    """Compare the `X-Webhook-Token` header against the shared token."""
+    token = lower_headers(headers).get("x-webhook-token")
+    if not token:
+        return False
+    return constant_time_equals(token.strip(), secret)
+
+
+def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent:
+    """Normalize a Jira delivery into a `WebhookEvent`."""
+    payload = json_body(body)
+    issue = payload.get("issue") or {}
+    fields = issue.get("fields") or {}
+    user = payload.get("user") or {}
+    return WebhookEvent(
+        provider="jira",
+        event_type=payload.get("webhookEvent", "unknown"),
+        delivery_id=str(payload.get("timestamp") or ""),
+        resource_id=issue.get("key"),
+        occurred_at=str(payload.get("timestamp")) if payload.get("timestamp") is not None else None,
+        scope=(fields.get("project") or {}).get("key"),
+        title=fields.get("summary"),
+        actor=user.get("displayName") or user.get("name"),
+        payload=payload,
+    )
+
+
+class JiraProvider(Provider):
+    """Jira's webhook provider, with its defaults pre-wired.
+
+    ```python
+    from flyte.extras.webhooks import WebhookAppEnvironment
+    from flyteplugins.jira import JiraProvider
+
+    app_env = WebhookAppEnvironment(name="webhooks", providers=[JiraProvider()])
+    ```
+
+    Jira does not sign its webhooks, so this provider authenticates with a
+    shared token instead and reports `signed=False` — which is what makes the
+    dashboard say so rather than implying a guarantee that is absent.
+
+    Args:
+        secret_env: Environment variable holding the secret, mounted from a
+            `flyte.Secret`. Override only if you store it under a non-standard
+            name; the default is what the docs and examples assume.
+    """
+
+    def __init__(self, *, secret_env: str = DEFAULT_SECRET_ENV) -> None:
+        super().__init__(
+            name="jira",
+            secret_env=secret_env,
+            verify=verify,
+            parse=parse,
+            signed=False,
+            setup_hint="Jira Settings -> System -> Webhooks (needs a proxy to inject X-Webhook-Token)",
+        )