docs(examples): SaaS integration recipes over the vendors' own SDKs

Worked examples for driving GitHub, Slack, Linear, ClickUp, and Jira from
Flyte, plus one app receiving webhooks from all five:

    providers=[GitHubProvider(), SlackProvider(), LinearProvider(),
               ClickUpProvider(), JiraProvider()]

The API calls go through each vendor's own maintained client -- PyGithub,
slack_sdk, jira, gql -- because a task is just a function and those are tested
against the live API by people who get deprecation notices first. What Flyte
contributes is the receiver, idempotent launching, and flyte.new_condition;
the review-gate example is here because the condition is the only part of it
that needed inventing.

Each plugin also ships its own single-product example; these are the
multi-product receiver and the task recipes it launches.

Task names are environment-qualified (github-triage.triage_pr). Bare names
never resolve, and both the Linear and Jira recipes define a triage_issue --
the qualifier is what keeps them apart.

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

examples/external_saas_integrations/README.md

@@ -0,0 +1,63 @@
+# External SaaS integrations
+
+Recipes for driving GitHub, Slack, Linear, ClickUp, and Jira from Flyte.
+
+There is deliberately **no Flyte client plugin** for these products. Each vendor
+already ships (or the community maintains) a Python client that is tested
+against the live API by people who get deprecation notices first, and a task is
+just a function — so calling `PyGithub` or `slack_sdk` from a task needs nothing
+in between. A wrapper here would only add a surface to keep in sync with someone
+else's release calendar.
+
+What *is* Flyte's job, and what these examples use from it:
+
+- **`flyte.extras.webhooks`** — ships with flyte: one app that authenticates an inbound
+  delivery with the product's own scheme, normalizes it into a single event
+  model, and launches a run once per event key with `idempotent_run`.
+- **`flyteplugins-webhooks-<product>`** — one small package per product,
+  contributing just its verification and parsing.
+- **`flyte.new_condition`** — park a run on a human decision, with a typed
+  payload coming back.
+
+## The examples
+
+| File | What it shows | Client |
+| --- | --- | --- |
+| `webhook_receiver.py` | One app receiving from all five products, launching a task per event | `flyteplugins-webhooks-*` |
+| `github_pr_review_gate.py` | Human-gated merge: a condition carrying JSON, parsed into a typed decision | `PyGithub` |
+| `github_triage_pr.py` | Label, comment, and report a check run | `PyGithub` |
+| `slack_notify.py` | Post, thread, react, answer a mention | `slack_sdk` |
+| `linear_triage_issue.py` | Query a backlog and comment, over GraphQL | `gql` |
+| `clickup_manage_ticket.py` | Open and close tickets, with a status pre-check | `httpx` |
+| `jira_manage_ticket.py` | Open, transition, and search issues | `jira` |
+
+Linear and ClickUp ship no official Python SDK. Linear's API is a single GraphQL
+endpoint, so `gql` is the maintained client; ClickUp's is a handful of REST
+calls, so `httpx` directly beats a thin third-party wrapper.
+
+## Putting it together
+
+The receiver and the tasks are separate on purpose: the app authenticates and
+dispatches, the tasks do the work and can be run, tested, and retried on their
+own.
+
+```bash
+# 1. deploy the tasks the receiver will launch
+flyte deploy examples/external_saas_integrations/github_triage_pr.py env
+flyte deploy examples/external_saas_integrations/slack_notify.py env
+
+# 2. run one directly, to confirm credentials work before any webhook is involved
+flyte run examples/external_saas_integrations/github_triage_pr.py triage_pr \
+    --repo <owner>/<repo> --number <pr>
+
+# 3. deploy the receiver and point each provider at the URL its dashboard shows
+python examples/external_saas_integrations/webhook_receiver.py
+```
+
+Task names are qualified by their environment when deployed — `triage_pr` in
+`github_triage_pr.py` becomes `github-triage.triage_pr`, which is what the
+receiver looks up. That qualifier is also what keeps the two `triage_issue`
+tasks here (Linear's and Jira's) from colliding.
+
+`plugins/webhooks/README.md` has the full end-to-end testing guide, including
+how to wire up each provider and what to check at every step.

examples/external_saas_integrations/clickup_manage_ticket.py

@@ -0,0 +1,90 @@
+"""Read and write ClickUp from tasks, with `httpx` against its REST v2 API.
+
+ClickUp ships no official Python SDK and the community ones are thin and
+sporadically maintained, so this calls the REST API directly with `httpx`
+rather than adding a dependency that wraps four endpoints.
+
+Requirements:
+    pip install flyte httpx
+
+Setup:
+    flyte create secret CLICKUP_TOKEN --value pk_...
+
+Usage:
+    flyte run examples/external_saas_integrations/clickup_manage_ticket.py \\
+        open_ticket --list_id <list-id> --name "From Flyte"
+"""
+
+import os
+
+import flyte
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("httpx")
+
+env = flyte.TaskEnvironment(
+    name="clickup-tickets",
+    image=image,
+    secrets=[flyte.Secret("CLICKUP_TOKEN", as_env_var="CLICKUP_TOKEN")],
+)
+
+API = "https://api.clickup.com/api/v2"
+
+
+def _client():
+    import httpx
+
+    return httpx.AsyncClient(base_url=API, headers={"Authorization": os.environ["CLICKUP_TOKEN"]}, timeout=30)
+
+
+@env.task
+async def open_ticket(list_id: str, name: str, description: str = "") -> str:
+    """Create a task and return its URL."""
+    async with _client() as client:
+        response = await client.post(f"/list/{list_id}/task", json={"name": name, "description": description})
+        response.raise_for_status()
+        return response.json()["url"]
+
+
+@env.task
+async def triage_task(task_id: str) -> str:
+    """Comment on a newly created task.
+
+    This is what `webhook_receiver.py` launches for every `taskCreated`.
+    """
+    async with _client() as client:
+        task = await client.get(f"/task/{task_id}")
+        task.raise_for_status()
+        status = (task.json().get("status") or {}).get("status")
+        posted = await client.post(
+            f"/task/{task_id}/comment", json={"comment_text": f"Flyte triaged this ticket (status: {status})."}
+        )
+        posted.raise_for_status()
+    return f"triaged {task_id}"
+
+
+@env.task
+async def close_ticket(task_id: str, done_status: str = "done") -> str:
+    """Move a ticket to a Done-like status, validating it first.
+
+    ClickUp rejects transitions to statuses the ticket's list does not define,
+    with an opaque 400 — so check the list's statuses before trying.
+    """
+    async with _client() as client:
+        task = await client.get(f"/task/{task_id}")
+        task.raise_for_status()
+        list_id = (task.json().get("list") or {}).get("id")
+
+        listing = await client.get(f"/list/{list_id}")
+        listing.raise_for_status()
+        valid = [s["status"] for s in listing.json().get("statuses", [])]
+        if done_status not in valid:
+            raise ValueError(f"status {done_status!r} is not defined on list {list_id}; valid: {valid}")
+
+        updated = await client.put(f"/task/{task_id}", json={"status": done_status})
+        updated.raise_for_status()
+    return f"{task_id} -> {done_status}"
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    print(flyte.run(open_ticket, list_id="LIST_ID", name="Flyte test ticket").url)

examples/external_saas_integrations/github_pr_review_gate.py

@@ -0,0 +1,213 @@
+"""Human-gated PR merging: a condition carrying a JSON payload.
+
+The headline pattern. A task collects review metadata from a pull request,
+embeds it as JSON in a markdown condition prompt, parks the run until a human
+responds in the Flyte UI, and parses the structured response into a typed
+decision the workflow branches on. Approved PRs get merged.
+
+Conditions are Flyte's; talking to GitHub is PyGithub's. Nothing here wraps the
+GitHub API — `flyte.new_condition` is the only part that needed inventing.
+
+Requirements:
+    pip install flyte PyGithub
+
+Setup:
+    flyte create secret GITHUB_TOKEN --value <token-with-repo-scope>
+
+Usage:
+    flyte run examples/external_saas_integrations/github_pr_review_gate.py \\
+        gated_merge --repo octocat/hello-world --number 1
+"""
+
+import asyncio
+import json
+import os
+from datetime import timedelta
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+import flyte
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("PyGithub", "pydantic")
+
+env = flyte.TaskEnvironment(
+    name="github-review-gate",
+    image=image,
+    secrets=[flyte.Secret("GITHUB_TOKEN", as_env_var="GITHUB_TOKEN")],
+)
+
+Verdict = Literal["approve", "request_changes", "comment"]
+
+
+class ReviewComment(BaseModel):
+    """A single inline review comment."""
+
+    path: str
+    line: int | None = None
+    body: str
+    severity: Literal["info", "warning", "blocking"] = "info"
+
+
+class ReviewDecision(BaseModel):
+    """The reviewer's answer, parsed out of their condition response."""
+
+    verdict: Verdict
+    summary: str = ""
+    comments: list[ReviewComment] = Field(default_factory=list)
+
+    @property
+    def is_approved(self) -> bool:
+        return self.verdict == "approve"
+
+    @property
+    def blocking_comments(self) -> list[ReviewComment]:
+        return [c for c in self.comments if c.severity == "blocking"]
+
+
+def _normalize_verdict(value: str) -> Verdict:
+    v = value.strip().lower().replace(" ", "_").replace("-", "_")
+    if v in ("approve", "approved", "lgtm", "accept"):
+        return "approve"
+    if v in ("request_changes", "changes_requested", "reject", "blocked"):
+        return "request_changes"
+    if v in ("comment", "comments", "neutral", "note"):
+        return "comment"
+    raise ValueError(f"unknown verdict: {value!r}")
+
+
+def parse_review_payload(payload: str) -> ReviewDecision:
+    """Parse a reviewer's response into a `ReviewDecision`.
+
+    Accepts raw JSON, JSON inside a fenced code block, or prose with a JSON
+    object somewhere in it — people paste all three. Verdict synonyms are
+    normalized.
+
+    Raises:
+        ValueError: when no JSON object with a recognizable verdict is found.
+    """
+    text = (payload or "").strip()
+    if not text:
+        raise ValueError("empty review payload")
+
+    decoder = json.JSONDecoder()
+    idx = text.find("{")
+    while idx != -1:
+        try:
+            obj, _ = decoder.raw_decode(text[idx:])
+        except json.JSONDecodeError:
+            obj = None
+        if isinstance(obj, dict) and "verdict" in obj:
+            comments = obj.get("comments") or []
+            return ReviewDecision(
+                verdict=_normalize_verdict(str(obj["verdict"])),
+                summary=str(obj.get("summary") or ""),
+                comments=[ReviewComment.model_validate(c) for c in comments if isinstance(c, dict)],
+            )
+        idx = text.find("{", idx + 1)
+    raise ValueError(f"could not extract a review decision from payload: {text[:200]!r}")
+
+
+def _collect_context(repo: str, number: int, max_files: int = 50) -> dict[str, Any]:
+    """Gather what a reviewer needs, using PyGithub."""
+    from github import Auth, Github
+
+    with Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"])) as gh:
+        pr = gh.get_repo(repo).get_pull(number)
+        files = [
+            {
+                "filename": f.filename,
+                "status": f.status,
+                "additions": f.additions,
+                "deletions": f.deletions,
+                # Patches dominate the prompt; keep them for the first handful only.
+                "patch": f.patch if i < 20 else None,
+            }
+            for i, f in enumerate(pr.get_files()[:max_files])
+        ]
+        return {
+            "repo": repo,
+            "number": number,
+            "title": pr.title,
+            "author": pr.user.login if pr.user else None,
+            "body": pr.body or "",
+            "base": pr.base.ref,
+            "head": pr.head.ref,
+            "url": pr.html_url,
+            "additions": pr.additions,
+            "deletions": pr.deletions,
+            "changed_files": pr.changed_files,
+            "files": files,
+            "prior_reviews": [{"user": r.user.login if r.user else None, "state": r.state} for r in pr.get_reviews()],
+        }
+
+
+def build_review_prompt(context: dict[str, Any], instructions: str = "") -> str:
+    """Build the markdown prompt the reviewer sees in the Flyte UI.
+
+    The metadata goes in a fenced JSON block so it renders verbatim and can be
+    machine-read downstream.
+    """
+    instructions = instructions or (
+        "Review this pull request. Respond with a JSON object of the form:\n"
+        '`{"verdict": "approve" | "request_changes" | "comment", '
+        '"summary": "...", "comments": [{"path": "...", "line": 1, '
+        '"body": "...", "severity": "info" | "warning" | "blocking"}]}`'
+    )
+    return (
+        f"## Review requested: {context['repo']}#{context['number']}\n\n"
+        f"**{context['title']}** (by {context.get('author') or 'unknown'})\n\n"
+        f"{context.get('body', '')}\n\n"
+        f"{instructions}\n\n"
+        "### Pull request metadata\n\n"
+        "```json\n"
+        f"{json.dumps(context, indent=2)}\n"
+        "```\n"
+    )
+
+
+@env.task
+async def review_pr(repo: str, number: int, timeout: timedelta | None = None) -> ReviewDecision:
+    """Park the run on a human review condition and return the decision."""
+    context = await asyncio.to_thread(_collect_context, repo, number)
+    condition = await flyte.new_condition.aio(
+        f"review-{repo.replace('/', '-')}-{number}"[:60],
+        prompt=build_review_prompt(context),
+        prompt_type="markdown",
+        data_type=str,
+        timeout=timeout,
+    )
+    return parse_review_payload(await condition.wait.aio())
+
+
+@env.task
+async def gated_merge(repo: str, number: int) -> str:
+    """Wait for a human review, then merge if approved."""
+    decision = await review_pr(repo, number)
+
+    if not decision.is_approved:
+        await asyncio.to_thread(_comment, repo, number, f"Review gate blocked this merge: {decision.summary}")
+        return f"blocked: {decision.summary}"
+
+    return await asyncio.to_thread(_merge, repo, number)
+
+
+def _comment(repo: str, number: int, body: str) -> None:
+    from github import Auth, Github
+
+    with Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"])) as gh:
+        gh.get_repo(repo).get_issue(number).create_comment(body)
+
+
+def _merge(repo: str, number: int) -> str:
+    from github import Auth, Github
+
+    with Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"])) as gh:
+        result = gh.get_repo(repo).get_pull(number).merge(merge_method="squash")
+    return f"merged {result.sha}"
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    run = flyte.with_runcontext().run(gated_merge, repo="octocat/hello-world", number=1)
+    print(run.url)