Add Jira plugin: tasks, webhook app, MCP server

[cosmicBboy]

Adds plugins/jira (flyteplugins-jira), a Jira Cloud integration for Flyte 2 (sixth of the integration plugins alongside GitHub/Slack/Linear/ClickUp/Notion).

What's included

Read/write from tasks — JiraClient, an async REST v3 client covering projects, issues, JQL search, comments, and workflow transitions. Plain-text descriptions/comments are converted to Atlassian Document Format automatically (and back to plain text on read). Basic auth over account email + API token, all mounted from flyte.Secrets (JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN). 429 rate limits retried; errors raised as JiraAPIError with Jira's error messages.

React to Jira events — JiraAppEnvironment serves a setup/management dashboard (/) with end-to-end setup instructions (API token creation, flyte create secret commands, webhook config) and status/verify endpoints, plus a webhook receiver (/webhook) protected by a shared X-Webhook-Token header — Jira webhooks are not signed, and the dashboard honestly documents the token-via-gateway pattern and the network-level fallback. Payloads are normalized into JiraEvent objects, matched against an optional project allowlist, and dispatched to on_event handlers (jira:issue_created, jira:issue_updated, comment_created, ...). launch_task launches runs idempotently via dedupe labels, so webhook redeliveries never launch duplicate runs.

MCP server for agents on Flyte — the read/write surface doubles as MCP tools via build_mcp_server / jira_mcp_app_env. Read-only by default; read_only=False adds issue creation/updates/commenting/transitions; include_destructive=True additionally exposes delete_issue. Tool annotations come from the registry. Event ingestion is intentionally not an MCP tool — that stays with the app environment.

Tests

57 tests covering the client (respx-mocked Jira API, including basic-auth header, ADF conversion, and transition-by-name resolution), webhook token verification and event normalization, the MCP tool registry/server, dispatch idempotency, and the app dashboard/receiver endpoints.

Examples

• examples/manage_ticket.py — open/transition/search tickets
• examples/react_to_jira_events.py — webhook app launching idempotent runs
• examples/jira_mcp_server.py — MCP server for agents

Review pass

A follow-up commit fixes issues found while reviewing this branch.

Robustness and security

• The webhook token compares as bytes. hmac.compare_digest raises TypeError on str operands containing non-ASCII, and X-Webhook-Token is attacker-controlled: ASGI servers hand Starlette raw header bytes which it decodes as latin-1, so a crafted header turned a clean 401 into a 500. This matters more here than elsewhere, since the token is the whole authentication story for unsigned Jira webhooks.
• ⚠️ Behavior change: the project_keys allowlist now fails closed. Events it cannot attribute to a project are skipped rather than dispatched, matching the GitHub and Slack plugins. Previously an event with no project key bypassed the allowlist entirely.
• Retry-After is parsed defensively and clamped at 60s. The header may carry an HTTP-date, which raised ValueError, and a large value would previously have slept unbounded.

Dashboard and docs

• The recent-events table read the 25 oldest events instead of the newest — [:25] on a deque that appends on the right — so it froze after the first 25 events.
• Allowlist values are HTML-escaped like every other interpolated value.
• The _dispatch module docstring said "Slack retries on non-2xx" (copy-paste from the Slack plugin).

3 new tests cover these.

Follow-up: async launching and label-only idempotency

launch_task no longer blocks the app's event loop. It and blocking_run are now async-first, wrapped with flyte's @syncify, so handlers await launch_task.aio(...). Previously the synchronous call stalled the whole event loop for the duration of two control-plane round-trips plus a launch — with every other in-flight webhook queued behind it, against sender timeouts measured in seconds. The synchronous form still works for scripts. A regression test asserts four concurrent launches overlap; against the old blocking call it measures 0.81s instead of 0.42s and fails.

Idempotency is now purely label-based. The run-name allocation is gone — it probed up to 32 candidate names via Run.get before launching under the winner. That raced with concurrent launches, silently capped how many runs one dedupe key could ever have, and treated a name as an identity it never was. Runs now carry only the dedupe=<key> label and the control plane assigns the name. run_name_for, RUN_NAME_MAX, and the prefix / run_name_base arguments are removed.

The dedupe key is explicitly caller-supplied. dedupe_key() is a sensible default, not a requirement — any string chooses a different idempotency scope.

The module docstring is also honest about the residual race: the label check is a read followed by a launch, so two simultaneous deliveries of one event can both launch. Redeliveries are seconds to minutes apart and dedupe reliably; closing the concurrent case needs a compare-and-set the control plane does not expose.

Follow-up: sync and async call forms on JiraClient

The 12 client methods are wrapped with flyte's @syncify, so each has two call forms — matching how the SDK itself exposes Run.listall, flyte.run, and flyte.serve:

# async: in `async def` tasks, webhook handlers, MCP tools
async with JiraClient() as client:
    result = await client.some_method.aio(...)

# blocking: in plain `def` tasks and scripts
with JiraClient() as client:          # note: `with`, not `async with`
    result = client.some_method(...)

__enter__/__exit__ were added so the blocking form is usable at all. They run __aenter__/__aexit__ on syncify's background loop — the same loop the syncified methods run on — so the httpx.AsyncClient is created and used on a single loop rather than straddling two.

Two call sites had to move to .aio() for correctness, not just style. Internal self. calls would otherwise deadlock, since syncify raises on a blocking call made from its own loop thread. And the MCP tool bridge (await getattr(client, name)(...)) would raise TypeError: object dict can't be used in 'await' expression on the returned value — and, had it not raised, would have stalled the MCP server's event loop for the duration of every tool call. Measured: 0 event-loop ticks during one blocking call.

The dynamic sync_*-method alternative was rejected: it works at runtime but both mypy and ty report "JiraClient" has no attribute "sync_..." and fall back to Any, so every typed caller breaks. @syncify in place resolves to SyncFunction[[...], ...] in both checkers. The package's mypy error count is unchanged at 12, all pre-existing, none in _client.py.

Tests, examples, and READMEs use .aio() on async paths and document both forms, including when not to reach for the blocking one.

Follow-up: typed event constants

on_event no longer needs hand-copied strings:

from flyteplugins.jira import events

@app_env.on_event(events.Issue.CREATED)
async def handle(event): ...

flyteplugins.jira.events adds 6 classes / 22 constants, following the ActionPhase pattern in flyte.models — str enums grouped by event type, so a member drops in wherever a pattern string is accepted and a typo fails at import rather than by silently never matching. The constants carry Jira's exact wire values, so you need not remember which names take the jira: prefix. Raw strings still work, for events the constants do not cover yet.

The enum base pins __str__/__format__ to str's. Without that, Python 3.11+ renders members as Class.MEMBER rather than the wire value — which would have leaked enum names into the dashboard and /api/status, since handler patterns flow into both.

Tests assert the constants equal what the parser actually produces (through the app's own _matches), that every ANY is the bare type its actions prefix, and that no value appears in two classes.

Follow-up: an end-to-end Testing guide

The README now ends with a numbered walkthrough against a real account, ordered so each step fails in isolation — exercise the client standalone before involving the platform, deploy the launched task before the app that looks it up, run it directly before any webhook is in play. Then wire up the provider, trigger a real event, and check the four places evidence lands: the provider's delivery log, /api/events, flyte get runs, and the resource itself. It ends with a troubleshooting table mapping each symptom to its cause, since 401, 503, and "200 but no run" are three different failures.

It also walks through the idempotency behaviour by hand, which is the part unit tests can only simulate.

Writing the guide surfaced a gap and it is fixed here: the triage_issue task react_to_jira_events.py launches was looked up by name but defined nowhere, so anyone following the README end to end would have hit a task-not-found error at the first real event.

Verified mechanically rather than by eye: every referenced example path resolves, every flyte create secret name matches the actual _config.py default, every flyte deploy <file> <env> names a real TaskEnvironment, every flyte run task is defined, and every example file still executes.