flyteplugins-github 2.7.0__py3-none-any.whl

flyteplugins/github/__init__.py

@@ -0,0 +1,113 @@
+"""GitHub webhooks for Flyte.
+
+Hand a `GitHubProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyte.extras.webhooks import WebhookAppEnvironment, run_once
+from flyteplugins.github import GitHubProvider, events
+
+app_env = WebhookAppEnvironment(
+    name="github-webhooks",
+    providers=[GitHubProvider()],
+    secrets=[flyte.Secret("GITHUB_WEBHOOK_SECRET", as_env_var="GITHUB_WEBHOOK_SECRET")],
+)
+
+
+@app_env.on_event(events.PullRequest.OPENED)
+async def triage(event):
+    import flyte.remote as remote
+
+    task = remote.Task.get(name="github-triage.triage_pr", auto_version="latest")
+    result = await run_once.aio(task, key=event.dedupe_key(), repo=event.scope)
+    if not result.created:
+        return {"skipped": result.run.name, "url": result.run.url}
+    return {"run": result.run.name}
+```
+
+## Human review gates
+
+`review_pr` parks a run on a `flyte.new_condition` carrying the pull request's
+metadata as JSON, waits for a human to answer in the Flyte UI, and returns a
+typed decision:
+
+```python
+from flyteplugins.github import review_pr
+
+
+@env.task
+async def gated_merge(repo: str, number: int) -> str:
+    decision = await review_pr(repo, number)
+    if decision.is_approved:
+        ...  # merge, with PyGithub
+    return f"blocked: {decision.summary}"
+```
+
+It lives here because the condition is the part only Flyte can do. Reading the
+pull request is `PyGithub`'s job, and this calls it directly rather than
+wrapping it — install `flyteplugins-github[review]` for that extra.
+
+Calling the GitHub API for anything else is not this plugin's job either; use
+`PyGithub` from your tasks. See `examples/external_saas_integrations`.
+"""
+
+import hashlib
+import hmac
+
+from . import events
+from ._provider import GitHubProvider, handshake, parse, verify
+from ._review import (
+    DEFAULT_TOKEN_ENV_VAR,
+    ReviewComment,
+    ReviewContext,
+    ReviewDecision,
+    Verdict,
+    build_review_prompt,
+    collect_review_context,
+    condition_name_for,
+    parse_review_payload,
+    review_pr,
+)
+
+__all__ = [
+    "DEFAULT_TOKEN_ENV_VAR",
+    "SAMPLE_DELIVERY",
+    "GitHubProvider",
+    "ReviewComment",
+    "ReviewContext",
+    "ReviewDecision",
+    "Verdict",
+    "build_review_prompt",
+    "collect_review_context",
+    "condition_name_for",
+    "events",
+    "handshake",
+    "parse",
+    "parse_review_payload",
+    "review_pr",
+    "verify",
+]
+
+
+def _sample_headers(body: bytes, secret: str) -> dict[str, str]:
+    signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    return {
+        "X-GitHub-Event": "pull_request",
+        "X-GitHub-Delivery": "00000000-0000-0000-0000-000000000000",
+        "X-Hub-Signature-256": f"sha256={signature}",
+    }
+
+
+#: A real `pull_request.opened` delivery, trimmed to the fields the parser reads.
+#: The conformance harness signs and replays it, so `verify` and `parse` are
+#: checked against an actual payload rather than against each other.
+SAMPLE_DELIVERY = (
+    _sample_headers,
+    (
+        b'{"action": "opened", "number": 7,'
+        b' "pull_request": {"number": 7, "title": "Add a feature",'
+        b' "html_url": "https://github.com/octo/repo/pull/7", "updated_at": "2024-01-01T00:00:00Z"},'
+        b' "repository": {"full_name": "octo/repo"}, "sender": {"login": "octocat"}}'
+    ),
+)

flyteplugins/github/_provider.py

@@ -0,0 +1,99 @@
+"""GitHub webhook verification and payload normalization."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Mapping
+
+from flyte.extras.webhooks import (
+    Provider,
+    SignatureError,
+    WebhookEvent,
+    constant_time_equals,
+    hex_hmac_sha256,
+    json_body,
+    lower_headers,
+)
+
+
+def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool:
+    """Verify the `X-Hub-Signature-256` HMAC over the raw body."""
+    signature = lower_headers(headers).get("x-hub-signature-256")
+    if not signature or not signature.startswith("sha256="):
+        return False
+    return constant_time_equals(hex_hmac_sha256(secret, body), signature.removeprefix("sha256="))
+
+
+def handshake(headers: Mapping[str, str], body: bytes) -> dict[str, Any] | None:
+    """Answer the `ping` GitHub sends when a webhook is created."""
+    if lower_headers(headers).get("x-github-event") == "ping":
+        return {"ok": True, "ping": True}
+    return None
+
+
+def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent:
+    """Normalize a GitHub delivery into a `WebhookEvent`."""
+    lowered = lower_headers(headers)
+    event_type = lowered.get("x-github-event")
+    if not event_type:
+        raise SignatureError("missing X-GitHub-Event header")
+    payload = json_body(body)
+
+    repo = payload.get("repository") or {}
+    issue_or_pr = payload.get("pull_request") or payload.get("issue") or {}
+    # `comment` covers issue_comment / commit_comment / review comments; `review`
+    # covers pull_request_review. Either identifies the event within its issue, so
+    # two comments on one issue do not collapse onto a single dedupe key.
+    comment = payload.get("comment") or payload.get("review") or {}
+    number = issue_or_pr.get("number")
+
+    resource = None
+    if repo.get("full_name") and number is not None:
+        resource = f"{repo['full_name']}#{number}"
+        if comment.get("id") is not None:
+            resource = f"{resource}:{comment['id']}"
+
+    return WebhookEvent(
+        provider="github",
+        event_type=event_type,
+        action=payload.get("action"),
+        delivery_id=lowered.get("x-github-delivery", ""),
+        resource_id=resource,
+        occurred_at=issue_or_pr.get("updated_at"),
+        scope=repo.get("full_name"),
+        title=issue_or_pr.get("title"),
+        url=comment.get("html_url") or issue_or_pr.get("html_url"),
+        actor=(payload.get("sender") or {}).get("login"),
+        payload=payload,
+    )
+
+
+class GitHubProvider(Provider):
+    """GitHub's webhook provider, with its defaults pre-wired.
+
+    ```python
+    from flyte.extras.webhooks import WebhookAppEnvironment
+    from flyteplugins.github import GitHubProvider
+
+    app_env = WebhookAppEnvironment(name="webhooks", providers=[GitHubProvider()])
+    ```
+
+    `WebhookAppEnvironment` mounts `default_secret_env` for you, so it does not
+    need naming again in `secrets=`.
+
+    Args:
+        secret_env: Environment variable holding the secret. Pass one only to
+            point this provider at a secret stored under a different name;
+            otherwise `default_secret_env` applies.
+    """
+
+    default_secret_env: ClassVar[str] = "GITHUB_WEBHOOK_SECRET"
+
+    def __init__(self, *, secret_env: str | None = None) -> None:
+        super().__init__(
+            name="github",
+            secret_env=secret_env or self.default_secret_env,
+            verify=verify,
+            parse=parse,
+            handshake=handshake,
+            setup_hint="repository Settings -> Webhooks -> Add webhook",
+        )

flyteplugins/github/_review.py

@@ -0,0 +1,310 @@
+"""Pull-request review gates built on `flyte.new_condition`.
+
+The 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 back into a typed `ReviewDecision`
+the workflow can branch on.
+
+This belongs in the plugin rather than in an example because the condition is
+the part that only Flyte can do. Reading the pull request is PyGithub's job, and
+this module calls it directly rather than wrapping it.
+
+`PyGithub` is an optional extra, so a webhook-only install stays lean:
+
+```bash
+pip install "flyteplugins-github[review]"
+```
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from datetime import timedelta
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+#: Environment variable holding the token used to read the pull request.
+DEFAULT_TOKEN_ENV_VAR = "GITHUB_TOKEN"
+
+#: Condition names are action names on the backend; keep them comfortably short.
+_MAX_CONDITION_NAME = 60
+
+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):
+    """Structured decision parsed from a reviewer's condition response."""
+
+    verdict: Verdict
+    summary: str = ""
+    comments: list[ReviewComment] = Field(default_factory=list)
+    reviewer: str | None = None
+
+    @property
+    def is_approved(self) -> bool:
+        """True when the reviewer approved the change."""
+        return self.verdict == "approve"
+
+    @property
+    def blocking_comments(self) -> list[ReviewComment]:
+        """Comments the reviewer flagged as blocking."""
+        return [c for c in self.comments if c.severity == "blocking"]
+
+
+class ReviewContext(BaseModel):
+    """Review metadata collected from a pull request.
+
+    This is the payload embedded in the condition prompt, so the reviewer sees
+    everything needed to decide without leaving the Flyte UI.
+    """
+
+    repo: str
+    number: int
+    title: str
+    author: str | None = None
+    body: str = ""
+    base: str | None = None
+    head: str | None = None
+    url: str | None = None
+    additions: int | None = None
+    deletions: int | None = None
+    changed_files: int | None = None
+    files: list[dict[str, Any]] = Field(default_factory=list)
+    prior_reviews: list[dict[str, Any]] = Field(default_factory=list)
+
+    def to_json(self, max_file_patches: int = 20) -> str:
+        """Serialize to JSON for embedding in a prompt.
+
+        Patches dominate the size of a large diff, so only the first
+        `max_file_patches` files keep theirs — the rest keep their stats.
+        """
+        data = self.model_dump()
+        for i, f in enumerate(data["files"]):
+            if i >= max_file_patches:
+                f.pop("patch", None)
+        return json.dumps(data, indent=2)
+
+
+def _github(token: str | None = None):
+    """Build a PyGithub client, with a useful error when the extra is missing."""
+    try:
+        from github import Auth, Github
+    except ModuleNotFoundError as exc:  # pragma: no cover - depends on extras
+        raise ModuleNotFoundError(
+            "PyGithub is not installed. Install 'flyteplugins-github[review]' to use the review gate."
+        ) from exc
+
+    resolved = token if token is not None else os.environ.get(DEFAULT_TOKEN_ENV_VAR)
+    if not resolved:
+        raise ValueError(
+            f"{DEFAULT_TOKEN_ENV_VAR} is not set. Create the secret and request it on the task's environment: "
+            f"secrets=[flyte.Secret('{DEFAULT_TOKEN_ENV_VAR}', as_env_var='{DEFAULT_TOKEN_ENV_VAR}')]"
+        )
+    return Github(auth=Auth.Token(resolved))
+
+
+def _collect_sync(repo: str, number: int, max_files: int, token: str | None) -> ReviewContext:
+    with _github(token) as gh:
+        pull = gh.get_repo(repo).get_pull(number)
+        files = [
+            {
+                "filename": f.filename,
+                "status": f.status,
+                "additions": f.additions,
+                "deletions": f.deletions,
+                "changes": f.changes,
+                "patch": f.patch,
+            }
+            for f in pull.get_files()[:max_files]
+        ]
+        try:
+            prior = [
+                {"user": r.user.login if r.user else None, "state": r.state, "body": r.body or ""}
+                for r in pull.get_reviews()
+            ]
+        except Exception:
+            # Prior reviews are context, not a requirement — a token without
+            # permission to list them should not block the gate.
+            prior = []
+        return ReviewContext(
+            repo=repo,
+            number=number,
+            title=pull.title,
+            author=pull.user.login if pull.user else None,
+            body=pull.body or "",
+            base=pull.base.ref,
+            head=pull.head.ref,
+            url=pull.html_url,
+            additions=pull.additions,
+            deletions=pull.deletions,
+            changed_files=pull.changed_files,
+            files=files,
+            prior_reviews=prior,
+        )
+
+
+async def collect_review_context(
+    repo: str,
+    number: int,
+    *,
+    max_files: int = 50,
+    token: str | None = None,
+) -> ReviewContext:
+    """Fetch a pull request and assemble the metadata a reviewer needs.
+
+    Args:
+        repo: Repository full name (`owner/repo`).
+        number: Pull request number.
+        max_files: Cap on how many changed files to include.
+        token: Explicit token; otherwise read from `GITHUB_TOKEN`.
+    """
+    # PyGithub is synchronous, so keep it off the caller's event loop.
+    return await asyncio.to_thread(_collect_sync, repo, number, max_files, token)
+
+
+def build_review_prompt(context: ReviewContext, instructions: str = "") -> str:
+    """Build the markdown prompt shown to the reviewer in the Flyte UI.
+
+    The metadata is embedded as a fenced JSON block so it renders verbatim and
+    can be machine-parsed 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.author or 'unknown'})\n\n"
+        f"{context.body}\n\n"
+        f"{instructions}\n\n"
+        "### Pull request metadata\n\n"
+        "```json\n"
+        f"{context.to_json()}\n"
+        "```\n"
+    )
+
+
+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 condition response into a `ReviewDecision`.
+
+    Accepts raw JSON, JSON inside a fenced code block, or prose with a JSON
+    object somewhere in it — reviewers paste all three. Verdict synonyms
+    (`approved`, `changes_requested`, `lgtm`, ...) are normalized.
+
+    Raises:
+        ValueError: when no JSON object with a recognizable verdict can be
+            extracted from the payload.
+    """
+    text = (payload or "").strip()
+    if not text:
+        raise ValueError("empty review payload")
+
+    # Scan every `{` and let raw_decode tolerate trailing content, so a JSON
+    # object wrapped in prose or a fenced block is still found.
+    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)],
+                reviewer=obj.get("reviewer"),
+            )
+        idx = text.find("{", idx + 1)
+    raise ValueError(f"could not extract a review decision from payload: {text[:200]!r}")
+
+
+def condition_name_for(repo: str, number: int) -> str:
+    """Derive a condition name from a pull request, within the length limit."""
+    name = f"review-{repo.replace('/', '-')}-{number}"
+    if len(name) <= _MAX_CONDITION_NAME:
+        return name
+    # Keep the number, which is what distinguishes one review from the next.
+    suffix = f"-{number}"
+    return name[: _MAX_CONDITION_NAME - len(suffix)] + suffix
+
+
+async def review_pr(
+    repo: str,
+    number: int,
+    *,
+    condition_name: str | None = None,
+    instructions: str = "",
+    timeout: timedelta | int | float | None = None,
+    max_files: int = 50,
+    token: str | None = None,
+) -> ReviewDecision:
+    """Park the run on a human review condition and return the decision.
+
+    Collects the pull request's metadata, raises a markdown condition carrying
+    it as JSON, waits for a human to respond in the Flyte UI, and parses the
+    response into a typed decision:
+
+    ```python
+    @env.task
+    async def gated_merge(repo: str, number: int) -> str:
+        decision = await review_pr(repo, number)
+        if decision.is_approved:
+            ...
+        return f"blocked: {decision.summary}"
+    ```
+
+    Args:
+        repo: Repository full name (`owner/repo`).
+        number: Pull request number.
+        condition_name: Name of the condition action; defaults to one derived
+            from the repo and number.
+        instructions: Override for the reviewer instructions in the prompt.
+        timeout: Forwarded to `flyte.new_condition`. On expiry `wait()` raises
+            `flyte.errors.ConditionTimedoutError`.
+        max_files: Cap on how many changed files to include in the prompt.
+        token: Explicit token; otherwise read from `GITHUB_TOKEN`.
+
+    Returns:
+        The parsed `ReviewDecision`.
+
+    Raises:
+        ValueError: when the reviewer's response carries no recognizable verdict.
+    """
+    import flyte
+
+    context = await collect_review_context(repo, number, max_files=max_files, token=token)
+    condition = await flyte.new_condition.aio(
+        condition_name or condition_name_for(repo, number),
+        prompt=build_review_prompt(context, instructions=instructions),
+        prompt_type="markdown",
+        data_type=str,
+        timeout=timeout,
+    )
+    return parse_review_payload(await condition.wait.aio())

flyteplugins/github/events.py

@@ -0,0 +1,167 @@
+"""GitHub webhook events (the `X-GitHub-Event` header plus the payload action)."""
+
+from __future__ import annotations
+
+from flyte.extras.webhooks import EventType
+
+__all__ = [
+    "CheckRun",
+    "CheckSuite",
+    "Create",
+    "Delete",
+    "Fork",
+    "IssueComment",
+    "Issues",
+    "PullRequest",
+    "PullRequestReview",
+    "PullRequestReviewComment",
+    "Push",
+    "Release",
+    "Star",
+    "WorkflowRun",
+]
+
+
+class PullRequest(EventType):
+    """`pull_request` events."""
+
+    ANY = "pull_request"
+    OPENED = "pull_request.opened"
+    CLOSED = "pull_request.closed"
+    """Fires on merge and on close-without-merge; check `payload["pull_request"]["merged"]`."""
+    REOPENED = "pull_request.reopened"
+    EDITED = "pull_request.edited"
+    ASSIGNED = "pull_request.assigned"
+    UNASSIGNED = "pull_request.unassigned"
+    LABELED = "pull_request.labeled"
+    UNLABELED = "pull_request.unlabeled"
+    SYNCHRONIZE = "pull_request.synchronize"
+    """New commits were pushed to the PR's head branch."""
+    READY_FOR_REVIEW = "pull_request.ready_for_review"
+    CONVERTED_TO_DRAFT = "pull_request.converted_to_draft"
+    REVIEW_REQUESTED = "pull_request.review_requested"
+    REVIEW_REQUEST_REMOVED = "pull_request.review_request_removed"
+    LOCKED = "pull_request.locked"
+    UNLOCKED = "pull_request.unlocked"
+
+
+class Issues(EventType):
+    """`issues` events. Note GitHub's event type is plural."""
+
+    ANY = "issues"
+    OPENED = "issues.opened"
+    CLOSED = "issues.closed"
+    REOPENED = "issues.reopened"
+    EDITED = "issues.edited"
+    ASSIGNED = "issues.assigned"
+    UNASSIGNED = "issues.unassigned"
+    LABELED = "issues.labeled"
+    UNLABELED = "issues.unlabeled"
+    MILESTONED = "issues.milestoned"
+    DEMILESTONED = "issues.demilestoned"
+    PINNED = "issues.pinned"
+    UNPINNED = "issues.unpinned"
+    LOCKED = "issues.locked"
+    UNLOCKED = "issues.unlocked"
+    TRANSFERRED = "issues.transferred"
+    DELETED = "issues.deleted"
+
+
+class IssueComment(EventType):
+    """`issue_comment` events, on both issues and pull requests."""
+
+    ANY = "issue_comment"
+    CREATED = "issue_comment.created"
+    EDITED = "issue_comment.edited"
+    DELETED = "issue_comment.deleted"
+
+
+class PullRequestReview(EventType):
+    """`pull_request_review` events."""
+
+    ANY = "pull_request_review"
+    SUBMITTED = "pull_request_review.submitted"
+    EDITED = "pull_request_review.edited"
+    DISMISSED = "pull_request_review.dismissed"
+
+
+class PullRequestReviewComment(EventType):
+    """`pull_request_review_comment` events — inline comments on a diff."""
+
+    ANY = "pull_request_review_comment"
+    CREATED = "pull_request_review_comment.created"
+    EDITED = "pull_request_review_comment.edited"
+    DELETED = "pull_request_review_comment.deleted"
+
+
+class Push(EventType):
+    """`push` events. GitHub sends no action, so there is only `ANY`."""
+
+    ANY = "push"
+
+
+class Create(EventType):
+    """`create` events — a branch or tag was created. No action."""
+
+    ANY = "create"
+
+
+class Delete(EventType):
+    """`delete` events — a branch or tag was deleted. No action."""
+
+    ANY = "delete"
+
+
+class Fork(EventType):
+    """`fork` events. No action."""
+
+    ANY = "fork"
+
+
+class Release(EventType):
+    """`release` events."""
+
+    ANY = "release"
+    PUBLISHED = "release.published"
+    UNPUBLISHED = "release.unpublished"
+    CREATED = "release.created"
+    EDITED = "release.edited"
+    DELETED = "release.deleted"
+    PRERELEASED = "release.prereleased"
+    RELEASED = "release.released"
+
+
+class WorkflowRun(EventType):
+    """`workflow_run` events — GitHub Actions run lifecycle."""
+
+    ANY = "workflow_run"
+    REQUESTED = "workflow_run.requested"
+    IN_PROGRESS = "workflow_run.in_progress"
+    COMPLETED = "workflow_run.completed"
+
+
+class CheckRun(EventType):
+    """`check_run` events."""
+
+    ANY = "check_run"
+    CREATED = "check_run.created"
+    COMPLETED = "check_run.completed"
+    REREQUESTED = "check_run.rerequested"
+    REQUESTED_ACTION = "check_run.requested_action"
+
+
+class CheckSuite(EventType):
+    """`check_suite` events."""
+
+    ANY = "check_suite"
+    COMPLETED = "check_suite.completed"
+    REQUESTED = "check_suite.requested"
+    REREQUESTED = "check_suite.rerequested"
+
+
+class Star(EventType):
+    """`star` events."""
+
+    ANY = "star"
+    CREATED = "star.created"
+    DELETED = "star.deleted"

flyteplugins_github-2.7.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: flyteplugins-github
+Version: 2.7.0
+Summary: Receive GitHub webhooks in Flyte.
+Author: Flyte Contributors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: flyte
+Provides-Extra: app
+Requires-Dist: fastapi>=0.115; extra == "app"
+Requires-Dist: uvicorn>=0.30; extra == "app"
+Provides-Extra: review
+Requires-Dist: PyGithub>=2; extra == "review"
+
+# flyteplugins-github
+
+Receive GitHub webhooks in Flyte.
+
+```bash
+pip install "flyteplugins-github[app]"
+```
+
+## Using it
+
+Hand a `GitHubProvider()` to a `WebhookAppEnvironment` and register handlers with the
+typed constants in `events`:
+
+```python
+import flyte
+from flyte.extras.webhooks import WebhookAppEnvironment, run_once
+from flyteplugins.github import GitHubProvider, events
+
+# GitHubProvider.default_secret_env is mounted for you.
+app_env = WebhookAppEnvironment(name="github-webhooks", providers=[GitHubProvider()])
+
+
+@app_env.on_event(events.PullRequest.OPENED)
+async def handle(event):
+    import flyte.remote as remote
+
+    task = remote.Task.get(name="my-env.my_task", auto_version="latest")
+    result = await run_once.aio(task, key=event.dedupe_key(), resource=event.resource_id)
+    if not result.created:
+        return {"skipped": result.run.name, "url": result.run.url}
+    return {"run": result.run.name}
+
+
+flyte.serve(app_env)
+```
+
+Handlers must `await run_once.aio(...)`. The blocking form stalls the
+app's event loop, and GitHub times deliveries out in seconds.
+
+One app can serve several products at once — hand it one provider per product.
+
+## Human review gates
+
+`review_pr` parks a run on a `flyte.new_condition` carrying the pull request's
+metadata as JSON, waits for a human to answer in the Flyte UI, and returns a
+typed decision the workflow branches on:
+
+```python
+from flyteplugins.github import review_pr
+
+
+@env.task
+async def gated_merge(repo: str, number: int) -> str:
+    decision = await review_pr(repo, number)
+    if not decision.is_approved:
+        return f"blocked: {decision.summary}"
+    ...  # merge, with PyGithub
+    return "merged"
+```
+
+The reviewer answers in markdown; `parse_review_payload` accepts raw JSON, a
+fenced block, or JSON buried in prose, and normalizes verdict synonyms
+(`lgtm`, `approved`, `changes_requested`, ...) — because people paste all of
+those.
+
+This lives in the plugin because the condition is the part only Flyte can do.
+Reading the pull request is `PyGithub`'s job, which the gate calls directly
+rather than wrapping:
+
+```bash
+pip install "flyteplugins-github[review]"
+```
+
+## Try it
+
+`examples/github_webhooks.py` runs two ways. The first needs no GitHub account:
+
+```bash
+python examples/github_webhooks.py --local   # replay a real sample delivery in-process
+python examples/github_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 GITHUB_WEBHOOK_SECRET --value <secret>
+   ```
+2. Point GitHub at `<app-url>/webhook/github`, from
+   repository Settings → Webhooks → Add webhook, content type `application/json`.
+
+GitHub sends a `ping` when the webhook is created; it is answered automatically, so a green check in *Recent Deliveries* means the app is reachable.
+
+**Verification:** HMAC-SHA256 over the raw body (`X-Hub-Signature-256`).
+
+Comment and review events fold the comment id into `resource_id`, so two comments on one issue are two events rather than a redelivery of the first.
+
+## 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 GitHub API. Use `PyGithub` 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.

flyteplugins_github-2.7.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+flyteplugins/github/__init__.py,sha256=rNlGTRndjurjvDCKmaGqj1hiQGpS9woDlTYmRmGmJDk,3352
+flyteplugins/github/_provider.py,sha256=3mK9p-avlwR7G4j2l5FikwzaxRZVyuTR-9lHeGSI5Po,3556
+flyteplugins/github/_review.py,sha256=6XwWI-lOZ3DIshIRU8i-FrzepJtvXmaVm_wbFAA8Iuw,11037
+flyteplugins/github/events.py,sha256=_SghpvwL_m7RjPzVjMx04G-1OorNAI1275vVyuFSmkY,4358
+flyteplugins_github-2.7.0.dist-info/METADATA,sha256=ftkbcxjo2m22AivfHTpAv7hucezCNsnX2no5soIZba8,4231
+flyteplugins_github-2.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flyteplugins_github-2.7.0.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_github-2.7.0.dist-info/RECORD,,

flyteplugins_github-2.7.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flyteplugins_github-2.7.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flyteplugins