feat(webhooks): add flyteplugins-webhooks-jira

Receive Jira webhooks in Flyte. Implements the Provider 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 Jira can send.

Runs the shared conformance check, which replays a real SAMPLE_DELIVERY through
verify and parse rather than trusting them to agree with each other.

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

@@ -0,0 +1,69 @@
+# flyteplugins-webhooks-jira
+
+Receive Jira webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-webhooks-core[app]" flyteplugins-webhooks-jira
+```
+
+## Using it
+
+Hand `PROVIDER` 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.jira import PROVIDER, events
+
+app_env = WebhookAppEnvironment(
+    name="jira-webhooks",
+    providers=[PROVIDER],
+    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 more than one `PROVIDER`.
+
+## 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. `PROVIDER.signed` is 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/webhooks/jira/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "flyteplugins-webhooks-jira"
+dynamic = ["version"]
+description = "Receive Jira 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/jira/src/flyteplugins/webhooks/jira/__init__.py

@@ -0,0 +1,31 @@
+"""Jira webhooks for Flyte.
+
+Hand `PROVIDER` 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 PROVIDER, parse, verify
+
+__all__ = ["PROVIDER", "SAMPLE_DELIVERY", "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/webhooks/jira/src/flyteplugins/webhooks/jira/_provider.py

@@ -0,0 +1,56 @@
+"""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. `PROVIDER.signed` is 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 flyteplugins.webhooks.core import (
+    Provider,
+    WebhookEvent,
+    constant_time_equals,
+    json_body,
+    lower_headers,
+)
+
+
+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")
+    return bool(token) and 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,
+    )
+
+
+#: The contract core needs to accept Jira webhooks.
+PROVIDER = Provider(
+    name="jira",
+    secret_env="JIRA_WEBHOOK_TOKEN",
+    verify=verify,
+    parse=parse,
+    signed=False,
+    setup_hint="Jira Settings -> System -> Webhooks (needs a proxy to inject X-Webhook-Token)",
+)

plugins/webhooks/jira/src/flyteplugins/webhooks/jira/events.py

@@ -0,0 +1,63 @@
+"""Jira webhook events, from the payload's `webhookEvent` field.
+
+Some names take a `jira:` prefix and some do not — that inconsistency is Jira's.
+These constants carry the exact wire values so you need not remember which.
+"""
+
+from __future__ import annotations
+
+from flyteplugins.webhooks.core import EventType
+
+__all__ = ["Comment", "Issue", "Project", "Sprint", "Version", "Worklog"]
+
+
+class Issue(EventType):
+    """Issue events. Note the `jira:` prefix, which comment events lack."""
+
+    CREATED = "jira:issue_created"
+    UPDATED = "jira:issue_updated"
+    DELETED = "jira:issue_deleted"
+
+
+class Comment(EventType):
+    """Comment events. These carry no `jira:` prefix."""
+
+    CREATED = "comment_created"
+    UPDATED = "comment_updated"
+    DELETED = "comment_deleted"
+
+
+class Worklog(EventType):
+    """Worklog events."""
+
+    CREATED = "worklog_created"
+    UPDATED = "worklog_updated"
+    DELETED = "worklog_deleted"
+
+
+class Project(EventType):
+    """Project events."""
+
+    CREATED = "project_created"
+    UPDATED = "project_updated"
+    DELETED = "project_deleted"
+
+
+class Version(EventType):
+    """Version (release) events."""
+
+    CREATED = "jira:version_created"
+    UPDATED = "jira:version_updated"
+    RELEASED = "jira:version_released"
+    UNRELEASED = "jira:version_unreleased"
+    DELETED = "jira:version_deleted"
+
+
+class Sprint(EventType):
+    """Sprint events (Jira Software)."""
+
+    CREATED = "sprint_created"
+    UPDATED = "sprint_updated"
+    STARTED = "sprint_started"
+    CLOSED = "sprint_closed"
+    DELETED = "sprint_deleted"

plugins/webhooks/jira/tests/test_conformance.py

@@ -0,0 +1,16 @@
+"""Every provider plugin runs the same conformance check.
+
+CI fails here if this plugin drifts from the shared format: a verifier that
+raises instead of returning False, event constants that render as enum names, a
+sample delivery that no constant spells, an unstable dedupe key.
+"""
+
+from __future__ import annotations
+
+from flyteplugins.webhooks.core.testing import assert_provider_conforms
+
+import flyteplugins.webhooks.jira as plugin
+
+
+def test_conformance():
+    assert_provider_conforms(plugin)

plugins/webhooks/jira/tests/test_jira.py

@@ -0,0 +1,51 @@
+"""Jira-specific verification and normalization, beyond conformance."""
+
+from __future__ import annotations
+
+import json
+
+from flyteplugins.webhooks.jira import PROVIDER, events, parse, verify
+
+TOKEN = "jira-token"
+
+
+def _parse(payload: dict):
+    body = json.dumps(payload).encode()
+    return parse({"X-Webhook-Token": TOKEN}, body)
+
+
+def test_the_shared_token_is_compared_not_a_signature():
+    assert verify(b"anything", {"X-Webhook-Token": TOKEN}, TOKEN) is True
+    assert verify(b"anything", {"X-Webhook-Token": "wrong"}, TOKEN) is False
+    assert verify(b"anything", {}, TOKEN) is False
+
+
+def test_the_provider_declares_itself_unsigned():
+    """Jira does not sign; the dashboard says so rather than implying otherwise."""
+    assert PROVIDER.signed is False
+
+
+def test_the_webhook_event_name_is_the_qualified_type():
+    assert (
+        _parse({"webhookEvent": "jira:issue_created", "issue": {"key": "PROJ-1", "fields": {}}}).qualified_type
+        == events.Issue.CREATED
+    )
+
+
+def test_comment_events_carry_no_jira_prefix():
+    """That inconsistency is Jira's; the constants carry the exact wire values."""
+    assert (
+        _parse({"webhookEvent": "comment_created", "issue": {"key": "PROJ-1", "fields": {}}}).qualified_type
+        == events.Comment.CREATED
+    )
+
+
+def test_the_project_key_comes_from_issue_fields():
+    event = _parse(
+        {
+            "webhookEvent": "jira:issue_created",
+            "issue": {"key": "PROJ-1", "fields": {"project": {"key": "PROJ"}, "summary": "A bug"}},
+        }
+    )
+    assert event.scope == "PROJ"
+    assert event.resource_id == "PROJ-1"