docs(jira): add an end-to-end Testing guide to the README

A step-by-step pass a human can follow against a real account: create the
credentials, verify the client standalone, deploy the task the receiver
launches, run it directly, deploy the app, wire the provider up, trigger a
real event, and confirm idempotency. Ends with a troubleshooting table
mapping each failure mode to its cause.

Ordered so each step fails in isolation: the client is exercised before the
platform, and the launched task is deployed before the app that looks it up.

Also adds the `triage_issue` task the webhook example launches. It was looked
up by name but defined nowhere, so the example could not work as written.
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

@@ -183,3 +183,121 @@ agent = Agent(
 path, timeouts, and retries. The module exports `default_config`; pass a custom
 `Config` to `JiraClient`, `build_mcp_server`, or the app environment when you
 need it.
+
+## Testing
+
+An end-to-end pass against a real Jira Cloud site. Use a scratch project —
+step 4 creates and comments on real issues.
+
+**1. Create the credentials.** An API token from
+<https://id.atlassian.com/manage-profile/security/api-tokens>. Jira uses basic
+auth over your account email plus the token, so all three values are secrets:
+
+```bash
+flyte create secret JIRA_BASE_URL  --value https://<your-site>.atlassian.net
+flyte create secret JIRA_EMAIL     --value you@example.com
+flyte create secret JIRA_API_TOKEN --value <api-token>
+flyte create secret JIRA_WEBHOOK_TOKEN --value <random-string>
+```
+
+`JIRA_WEBHOOK_TOKEN` is a value you invent. Jira webhooks are **not signed**,
+so the receiver authenticates them with this shared token instead — see step 6.
+
+**2. Check the client works before involving the platform:**
+
+```bash
+export JIRA_BASE_URL=https://<your-site>.atlassian.net
+export JIRA_EMAIL=you@example.com
+export JIRA_API_TOKEN=<api-token>
+python -c "
+from flyteplugins.jira import JiraClient
+with JiraClient() as c:
+    print(c.get_myself()['displayName'])
+    print([p['key'] for p in c.list_projects()])
+"
+```
+
+A 401 here is almost always the email/token pair rather than the token alone.
+
+**3. Deploy the task the webhook will launch.**
+
+```bash
+flyte deploy plugins/jira/examples/manage_ticket.py env
+```
+
+`react_to_jira_events.py` looks this task up by name (`triage_issue`), so it
+has to exist before the app can launch it.
+
+**4. Run a task directly**, to confirm writes land before any webhook is
+involved:
+
+```bash
+flyte run plugins/jira/examples/manage_ticket.py open_ticket \
+    --project_key <PROJ> --summary "Flyte test issue" --description "created by the plugin test"
+```
+
+**5. Deploy the webhook app.**
+
+```bash
+python plugins/jira/examples/react_to_jira_events.py
+```
+
+It prints the app URL. Open it: the dashboard should show all four secrets
+mounted, and *Verify Jira credentials* should return your display name.
+
+**6. Point Jira at the app.** Jira Settings → System → Webhooks → *Create a
+Webhook*:
+
+- URL: `<app-url>/webhook`
+- Events: *Issue created* and *Issue updated*
+
+Jira cannot add custom headers, and it does not sign its webhooks — so the
+`X-Webhook-Token` header the receiver requires has to be injected by whatever
+sits in front of the app (an API gateway, a reverse proxy, or a small
+forwarder). For a first local test, deploy the app with
+`require_webhook_token=False` and protect it at the network level instead,
+then send a delivery by hand to confirm the path works:
+
+```bash
+curl -X POST <app-url>/webhook \
+  -H 'Content-Type: application/json' \
+  -H 'X-Webhook-Token: <the value you chose>' \
+  -d '{"webhookEvent":"jira:issue_created","issue":{"key":"PROJ-1","fields":{"summary":"hand-made","project":{"key":"PROJ"}}}}'
+```
+
+**7. Trigger a real event.** Create an issue in the test project. Then check,
+in order:
+
+- `<app-url>/api/events` — the normalized event, `qualified_type` of
+  `jira:issue_created`.
+- `flyte get runs` — a run whose `dedupe` label matches.
+- The issue — the triage task's comment.
+
+**8. Confirm idempotency.** The dedupe key folds in Jira's event timestamp, so
+a redelivered event dedupes while a later update to the same issue gets its own
+run.
+
+**9. Optional — the allowlist.** Redeploy with `project_keys=["<PROJ>"]` and
+create an issue in another project. The receiver should answer 200 with a
+`skipped` message. The allowlist fails closed, so an event carrying no project
+key is skipped too.
+
+**10. Optional — the MCP server.**
+
+```bash
+python plugins/jira/examples/jira_mcp_server.py
+claude mcp add --transport http jira-mcp <app-url>/mcp/mcp
+```
+
+Ask an agent to summarize open bugs in the project. The default surface is
+read-only.
+
+### Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| Delivery returns 401 | The `X-Webhook-Token` header is missing or does not match `JIRA_WEBHOOK_TOKEN`. Jira alone cannot send it — see step 6. |
+| Delivery returns 503 | `JIRA_WEBHOOK_TOKEN` is not mounted; check `/api/status`. |
+| Client raises 401 | Basic auth needs the *email + token* pair, not the token alone. |
+| A description shows as `[object Object]` | Jira v3 stores rich text as ADF; the client converts plain strings for you, so pass a plain string. |
+| 200 but no run | No handler matched, or the allowlist skipped it — the response body says which. |

plugins/jira/examples/manage_ticket.py

@@ -61,6 +61,19 @@ async def summarize_open_bugs(project_key: str) -> str:
     return "\n".join(f"{i['key']} [{i['priority']}] {i['summary']}" for i in issues[:20])
 
 
+@env.task
+async def triage_issue(issue_key: str) -> str:
+    """Comment on a newly created issue.
+
+    This is the task `react_to_jira_events.py` launches for every
+    `jira:issue_created` event.
+    """
+    async with JiraClient() as client:
+        issue = await client.get_issue.aio(issue_key)
+        await client.add_comment.aio(issue_key, f"Flyte triaged this issue (status: {issue.get('status')}).")
+    return f"triaged {issue_key}"
+
+
 if __name__ == "__main__":
     # Replace with a project key you can access.
     flyte.run(summarize_open_bugs, project_key="PROJ")