flyteplugins-github 2.7.2__py3-none-any.whl → 2.8.0__py3-none-any.whl

flyteplugins/github/__init__.py

@@ -48,14 +48,31 @@ 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
+## GitHub App tokens
+
+Agents that clone, push, or open PRs authenticate best as a GitHub App,
+minting a short-lived installation token per operation instead of holding a
+personal access token:
+
+```python
+from flyteplugins.github import clone_url, mint_installation_token
+
+token = mint_installation_token()  # GITHUB_APP_ID / _INSTALLATION_ID / _PRIVATE_KEY
+url = clone_url("octo/repo", token)
+```
+
+It lives here because every agent otherwise carries its own copy of the same
+minting logic — install `flyteplugins-github[auth]` for that extra.
+
+Wrapping the GitHub API for anything else is not this plugin's job; use
 `PyGithub` from your tasks. See `examples/external_saas_integrations`.
 """
 
 import hashlib
 import hmac
 
-from . import events
+from . import events, payloads
+from ._app_auth import clone_url, mint_installation_token
 from ._provider import GitHubProvider, handshake, parse, verify
 from ._review import (
     DEFAULT_TOKEN_ENV_VAR,
@@ -79,12 +96,15 @@ __all__ = [
     "ReviewDecision",
     "Verdict",
     "build_review_prompt",
+    "clone_url",
     "collect_review_context",
     "condition_name_for",
     "events",
     "handshake",
+    "mint_installation_token",
     "parse",
     "parse_review_payload",
+    "payloads",
     "review_pr",
     "verify",
 ]

flyteplugins/github/_app_auth.py

@@ -0,0 +1,146 @@
+"""GitHub App installation tokens, for agents that clone, push, or open PRs.
+
+The pattern: hold no personal access token. Authenticate as a GitHub App and
+mint a short-lived installation token whenever one is needed. Tokens live one
+hour — plenty for a clone or a `gh pr create`, useless to an attacker who
+exfiltrates one from a log.
+
+This belongs in the plugin because every agent otherwise carries its own copy
+of the same fifty lines: sign an RS256 JWT as the app, trade it for an
+installation token, splice it into a clone URL. The webhook side of a GitHub
+agent already imports this package, so the auth side comes from it too.
+
+Inputs, all injected as Flyte secrets (or passed explicitly):
+
+  GITHUB_APP_ID               the app's numeric id
+  GITHUB_APP_INSTALLATION_ID  the installation's numeric id
+  GITHUB_APP_PRIVATE_KEY      the app's PEM private key
+
+The first two come off the app's *General* tab (App ID — not the Client ID
+beside it) and the URL you land on after installing the app,
+`.../settings/installations/<id>`. The third is the `.pem` from *Generate a
+private key*, which GitHub shows exactly once. Store them with:
+
+```bash
+flyte create secret github-app-id --value 1234567
+flyte create secret github-app-installation-id --value 87654321
+flyte create secret github-app-private-key --from-file ~/Downloads/app.private-key.pem
+```
+
+`--from-file` because a PEM is multi-line and a shell that eats the newlines
+yields a key that fails to parse here, at mint time. Mounted on a
+`TaskEnvironment` as `flyte.Secret("github-app-private-key")`, the kebab-case
+name upper-cases into the env var above with no `as_env_var=` needed. The
+README's "GitHub App tokens" section walks through all of it, including
+listing installation ids over the API instead of hunting for the URL.
+
+`GITHUB_TOKEN` and `GH_TOKEN` are honored as fallbacks so a deployment can
+migrate one secret at a time; once the app secrets exist the fallback never
+fires.
+
+`PyJWT[crypto]` signs the app JWT, so a webhook-only install stays lean:
+
+```bash
+pip install "flyteplugins-github[auth]"
+```
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import urllib.request
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+GITHUB_API = "https://api.github.com"
+#: App tokens authenticate with this literal username in clone URLs.
+GIT_USERNAME = "x-access-token"
+
+#: Environment variables the app credentials default to.
+DEFAULT_APP_ID_ENV = "GITHUB_APP_ID"
+DEFAULT_INSTALLATION_ID_ENV = "GITHUB_APP_INSTALLATION_ID"
+DEFAULT_PRIVATE_KEY_ENV = "GITHUB_APP_PRIVATE_KEY"
+
+#: Plain-token fallbacks, checked in order when the app credentials are absent.
+FALLBACK_TOKEN_ENVS = ("GITHUB_TOKEN", "GH_TOKEN")
+
+
+def _post_json(url: str, *, bearer: str) -> dict[str, Any]:
+    """POST to the GitHub API with a bearer credential and return the JSON."""
+    request = urllib.request.Request(
+        url,
+        method="POST",
+        headers={"Authorization": f"Bearer {bearer}", "Accept": "application/vnd.github+json"},
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def mint_installation_token(
+    *,
+    app_id: str | None = None,
+    installation_id: str | None = None,
+    private_key: str | None = None,
+) -> str | None:
+    """A fresh installation token, or None with a logged reason.
+
+    None means "proceed unauthenticated or not at all" — treat it the way a
+    missing token is treated today, so a half-configured deployment degrades
+    instead of crashing. Synchronous, one HTTPS round trip: call through
+    `asyncio.to_thread` from handlers and other async code.
+
+    Args:
+        app_id: The app's numeric id; otherwise read from `GITHUB_APP_ID`.
+        installation_id: The installation's numeric id; otherwise read from
+            `GITHUB_APP_INSTALLATION_ID`.
+        private_key: The app's PEM private key; otherwise read from
+            `GITHUB_APP_PRIVATE_KEY`.
+    """
+    app_id = app_id or os.environ.get(DEFAULT_APP_ID_ENV)
+    installation_id = installation_id or os.environ.get(DEFAULT_INSTALLATION_ID_ENV)
+    private_key = private_key or os.environ.get(DEFAULT_PRIVATE_KEY_ENV)
+
+    if not (app_id and installation_id and private_key):
+        for env in FALLBACK_TOKEN_ENVS:
+            fallback = os.environ.get(env)
+            if fallback:
+                logger.info("GitHub App credentials not set; using %s fallback", env)
+                return fallback
+        logger.warning(
+            "Neither the %s/%s/%s secrets nor a fallback token (%s) are set; "
+            "authenticated GitHub operations will be skipped",
+            DEFAULT_APP_ID_ENV,
+            DEFAULT_INSTALLATION_ID_ENV,
+            DEFAULT_PRIVATE_KEY_ENV,
+            "/".join(FALLBACK_TOKEN_ENVS),
+        )
+        return None
+
+    try:
+        import jwt  # PyJWT[crypto]
+    except ModuleNotFoundError as exc:  # pragma: no cover - depends on extras
+        raise ModuleNotFoundError(
+            "PyJWT is not installed. Install 'flyteplugins-github[auth]' to mint GitHub App tokens."
+        ) from exc
+
+    now = int(time.time())
+    # iat is backdated 60s because GitHub rejects JWTs it considers issued in
+    # the future, and clocks drift.
+    app_jwt = jwt.encode({"iat": now - 60, "exp": now + 600, "iss": app_id}, private_key, algorithm="RS256")
+    try:
+        data = _post_json(f"{GITHUB_API}/app/installations/{installation_id}/access_tokens", bearer=app_jwt)
+        return data["token"]
+    except Exception as exc:  # callers degrade, they don't crash
+        logger.warning("Could not mint a GitHub App installation token: %s", exc)
+        return None
+
+
+def clone_url(repo: str, token: str | None = None) -> str:
+    """An https clone URL for `repo` ("owner/name"), authenticated when a token is given."""
+    if token:
+        return f"https://{GIT_USERNAME}:{token}@github.com/{repo}.git"
+    return f"https://github.com/{repo}.git"

flyteplugins/github/_provider.py

@@ -1,7 +1,20 @@
-"""GitHub webhook verification and payload normalization."""
+"""GitHub webhook verification and payload normalization.
+
+GitHub delivers the same payload in two body shapes, chosen per webhook in the
+*Add webhook* form and signed the same way:
+
+* content type `application/json` — the JSON is the body;
+* content type `application/x-www-form-urlencoded` — the form's *default* —
+  the JSON arrives under a `payload=` form field.
+
+`verify` covers both, since the HMAC signs the raw body regardless of encoding.
+`parse` normalizes both into the same `WebhookEvent`, so a webhook left on the
+default content type still works.
+"""
 
 from __future__ import annotations
 
+import urllib.parse
 from typing import Any, ClassVar, Mapping
 
 from flyte.extras.webhooks import (
@@ -23,6 +36,30 @@ def verify(body: bytes, headers: Mapping[str, str], secret: str) -> bool:
     return constant_time_equals(hex_hmac_sha256(secret, body), signature.removeprefix("sha256="))
 
 
+def _form_payload(body: bytes) -> dict[str, Any] | None:
+    """Decode a form-encoded delivery's `payload` field, or None when the body is JSON.
+
+    GitHub's *Add webhook* form defaults the content type to
+    `application/x-www-form-urlencoded`, which wraps the JSON in a `payload=`
+    form field. Sniffing the body rather than trusting Content-Type keeps
+    `parse` a pure function of the delivery, which is what the conformance
+    harness replays.
+    """
+    if body[:1] in (b"{", b"["):
+        return None
+    try:
+        decoded = body.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+    if "=" not in decoded.split("&", 1)[0]:
+        return None
+    fields = {key: values[0] for key, values in urllib.parse.parse_qs(decoded, keep_blank_values=True).items()}
+    raw = fields.get("payload")
+    if raw is None:
+        raise SignatureError("form-encoded delivery carries no `payload` field")
+    return json_body(raw.encode("utf-8"))
+
+
 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":
@@ -31,12 +68,13 @@ def handshake(headers: Mapping[str, str], body: bytes) -> dict[str, Any] | None:
 
 
 def parse(headers: Mapping[str, str], body: bytes) -> WebhookEvent:
-    """Normalize a GitHub delivery into a `WebhookEvent`."""
+    """Normalize a GitHub delivery — JSON or form-encoded — 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)
+    form = _form_payload(body)
+    payload = form if form is not None else json_body(body)
 
     repo = payload.get("repository") or {}
     issue_or_pr = payload.get("pull_request") or payload.get("issue") or {}
@@ -77,6 +115,9 @@ class GitHubProvider(Provider):
     app_env = WebhookAppEnvironment(name="webhooks", providers=[GitHubProvider()])
     ```
 
+    Either content type in GitHub's *Add webhook* form works: `application/json`
+    and the default `application/x-www-form-urlencoded` normalize identically.
+
     `WebhookAppEnvironment` mounts `default_secret_env` for you, so it does not
     need naming again in `secrets=`.
 

flyteplugins/github/events.py

@@ -10,6 +10,8 @@ __all__ = [
     "Create",
     "Delete",
     "Fork",
+    "Installation",
+    "InstallationRepositories",
     "IssueComment",
     "Issues",
     "PullRequest",
@@ -159,6 +161,29 @@ class CheckSuite(EventType):
     REREQUESTED = "check_suite.rerequested"
 
 
+class Installation(EventType):
+    """`installation` events — the app itself was installed, removed, or re-permissioned.
+
+    Every GitHub App webhook receives these, whatever repository events it
+    subscribes to. No repository in the payload, so they dedupe per delivery.
+    """
+
+    ANY = "installation"
+    CREATED = "installation.created"
+    DELETED = "installation.deleted"
+    SUSPEND = "installation.suspend"
+    UNSUSPEND = "installation.unsuspend"
+    NEW_PERMISSIONS_ACCEPTED = "installation.new_permissions_accepted"
+
+
+class InstallationRepositories(EventType):
+    """`installation_repositories` events — repositories granted to or removed from the app."""
+
+    ANY = "installation_repositories"
+    ADDED = "installation_repositories.added"
+    REMOVED = "installation_repositories.removed"
+
+
 class Star(EventType):
     """`star` events."""
 

flyteplugins/github/payloads.py

@@ -0,0 +1,154 @@
+"""Typed views of GitHub payloads, for autocomplete inside handlers.
+
+`event.payload` is `dict[str, Any]` — correct, since it carries GitHub's JSON
+verbatim, but blind to write against. These TypedDicts spell the fields GitHub
+actually sends, so `payloads.pull_request(event)` gives editors and agents
+something to complete against:
+
+```python
+from flyteplugins.github import payloads
+
+@app_env.on_event(events.PullRequest.OPENED)
+async def on_primary(event):
+    payload = payloads.pull_request(event)
+    branch = payload["pull_request"]["head"]["ref"]
+    repo = payload["repository"]["full_name"]
+```
+
+The helpers are casts, not validators: the dict is returned untouched, and a
+field GitHub did not send is still a `KeyError` at runtime. Every class is
+`total=False` because GitHub's payloads vary by action and App permissions —
+treat presence the way you already would with a raw dict. Fields beyond these
+still exist in the dict; the types name the commonly-read ones, not the whole
+wire format.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypedDict, cast
+
+if TYPE_CHECKING:
+    from flyte.extras.webhooks import WebhookEvent
+
+__all__ = [
+    "Comment",
+    "GitRef",
+    "Issue",
+    "IssueCommentEvent",
+    "Label",
+    "PullRequest",
+    "PullRequestEvent",
+    "Repository",
+    "User",
+    "issue_comment",
+    "pull_request",
+]
+
+
+class User(TypedDict, total=False):
+    """An account — sender, author, assignee, owner."""
+
+    login: str
+    id: int
+    type: str
+    html_url: str
+
+
+class Label(TypedDict, total=False):
+    name: str
+    color: str
+    description: str
+
+
+class Repository(TypedDict, total=False):
+    full_name: str
+    name: str
+    html_url: str
+    clone_url: str
+    default_branch: str
+    private: bool
+    owner: User
+
+
+class GitRef(TypedDict, total=False):
+    """One side of a pull request — `head` or `base`."""
+
+    ref: str
+    sha: str
+    label: str
+    repo: Repository
+
+
+class PullRequest(TypedDict, total=False):
+    """`payload["pull_request"]` — the PR the event is about."""
+
+    number: int
+    title: str
+    body: str
+    state: str
+    draft: bool
+    merged: bool
+    html_url: str
+    user: User
+    labels: list[Label]
+    head: GitRef
+    base: GitRef
+    additions: int
+    deletions: int
+    changed_files: int
+
+
+class Issue(TypedDict, total=False):
+    """`payload["issue"]` — present on `issues` and `issue_comment` events.
+
+    A comment on a pull request also arrives as `issue_comment`; the issue then
+    carries a `pull_request` key, which is how the two are told apart.
+    """
+
+    number: int
+    title: str
+    body: str
+    state: str
+    html_url: str
+    user: User
+    labels: list[Label]
+    pull_request: dict[str, Any]
+
+
+class Comment(TypedDict, total=False):
+    id: int
+    body: str
+    html_url: str
+    user: User
+
+
+class PullRequestEvent(TypedDict, total=False):
+    """A `pull_request` delivery."""
+
+    action: str
+    number: int
+    pull_request: PullRequest
+    repository: Repository
+    sender: User
+    installation: dict[str, Any]
+
+
+class IssueCommentEvent(TypedDict, total=False):
+    """An `issue_comment` delivery — the comment-triggered-agent shape."""
+
+    action: str
+    issue: Issue
+    comment: Comment
+    repository: Repository
+    sender: User
+    installation: dict[str, Any]
+
+
+def pull_request(event: WebhookEvent) -> PullRequestEvent:
+    """Typed view of a `pull_request` delivery's payload. A cast, not validation."""
+    return cast("PullRequestEvent", event.payload)
+
+
+def issue_comment(event: WebhookEvent) -> IssueCommentEvent:
+    """Typed view of an `issue_comment` delivery's payload. A cast, not validation."""
+    return cast("IssueCommentEvent", event.payload)

flyteplugins_github-2.8.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: flyteplugins-github
+Version: 2.8.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"
+Provides-Extra: auth
+Requires-Dist: PyJWT[crypto]>=2; extra == "auth"
+
+# flyteplugins-github
+
+Receive GitHub webhooks in Flyte — JSON or form-encoded, GitHub signs both the
+same way — plus human review gates on pull requests and GitHub App
+installation tokens for agents that clone, push, or open PRs.
+
+```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, WebhookEvent, 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: WebhookEvent):
+    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, the same delivery replayed to show the
+dedupe key is stable, and the same delivery form-encoded (GitHub's default
+content type) landing on that same key.
+
+## Setup
+
+1. Invent a shared secret — nothing generates it for you — and store it under
+   the name the provider mounts, `GITHUB_WEBHOOK_SECRET`:
+   ```bash
+   openssl rand -hex 32
+   flyte create secret GITHUB_WEBHOOK_SECRET --value <secret>
+   ```
+2. Point GitHub at `<app-url>/webhook/github`, from
+   repository Settings → Webhooks → Add webhook, pasting that same string into
+   the webhook's **Secret** field. (A GitHub App has its own *Webhook* section
+   with the same two fields; either route reaches the same endpoint.) A
+   mismatch reads as a 401 in *Recent Deliveries*. Either content type works —
+   the form's default `application/x-www-form-urlencoded` wraps the JSON in a
+   `payload=` field and is unwrapped automatically; `application/json` keeps
+   the deliveries readable in *Recent Deliveries*.
+
+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`), whichever content type the webhook uses.
+
+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.
+
+## GitHub App tokens
+
+Agents that clone, push, or open PRs authenticate best as a GitHub App: hold
+no personal access token, mint a short-lived installation token per operation.
+Tokens live one hour — plenty for a clone or a `gh pr create`, useless to an
+attacker who exfiltrates one from a log:
+
+```python
+import asyncio
+
+from flyteplugins.github import clone_url, mint_installation_token
+
+
+@env.task
+async def open_fix_pr(repo: str) -> str:
+    # One HTTPS round trip; keep it off the event loop.
+    token = await asyncio.to_thread(mint_installation_token)
+    url = clone_url(repo, token)  # https://x-access-token:<token>@github.com/...
+    ...
+```
+
+```bash
+pip install "flyteplugins-github[auth]"
+```
+
+Configuration comes from three environment variables — `GITHUB_APP_ID`,
+`GITHUB_APP_INSTALLATION_ID`, and `GITHUB_APP_PRIVATE_KEY`. What follows is
+where those values come from, how to store them, how to get them onto a task,
+and what happens when they are absent.
+
+### Where the three values come from
+
+Create the app first, from **Settings → Developer settings → GitHub Apps → New
+GitHub App** ([github.com/settings/apps/new](https://github.com/settings/apps/new);
+for an org, **Organization settings → Developer settings → GitHub Apps**). Give
+it only the permissions the agent uses — *Contents: Read* to clone, *Read and
+write* to push, *Pull requests: Read and write* to open PRs, *Issues: Read and
+write* to comment. Then:
+
+| Value | Where |
+| --- | --- |
+| `GITHUB_APP_ID` | The app's **General** tab, under *About* → **App ID**. A short number. |
+| `GITHUB_APP_PRIVATE_KEY` | Same tab, **Private keys** → *Generate a private key*. Downloads a `.pem` file. |
+| `GITHUB_APP_INSTALLATION_ID` | Install the app (**Install App** tab), then read the number off the URL you land on. |
+
+Two things that reliably cost an hour:
+
+- **The App ID is not the Client ID.** The General tab shows both, and the
+  Client ID (`Iv23li...`) sits right next to the App ID. Signing a JWT with the
+  Client ID as the issuer fails at GitHub, not locally, so the error surfaces as
+  a failed mint rather than a bad value.
+- **The private key is shown once.** GitHub hands over the `.pem` at generation
+  and never again; losing it means generating a new one and deleting the old.
+  Store it in Flyte before deleting the download.
+
+The installation id is the fiddly one — it identifies *the app installed on one
+account*, not the app. After installing, the browser lands on
+`https://github.com/settings/installations/<id>` (or
+`https://github.com/organizations/<org>/settings/installations/<id>`), and the
+trailing number is it. To read it without the browser, ask the API — the app
+JWT is the only credential this needs, so it works before any installation
+token exists:
+
+```python
+import json, time, urllib.request
+import jwt  # from flyteplugins-github[auth]
+
+app_id, pem = "1234567", open("my-agent.private-key.pem").read()
+now = int(time.time())
+app_jwt = jwt.encode({"iat": now - 60, "exp": now + 600, "iss": app_id}, pem, algorithm="RS256")
+request = urllib.request.Request(
+    "https://api.github.com/app/installations",
+    headers={"Authorization": f"Bearer {app_jwt}", "Accept": "application/vnd.github+json"},
+)
+for installation in json.load(urllib.request.urlopen(request)):
+    print(installation["id"], installation["account"]["login"])
+```
+
+### Storing them as Flyte secrets
+
+```bash
+flyte create secret github-app-id --value 1234567
+flyte create secret github-app-installation-id --value 87654321
+flyte create secret github-app-private-key --from-file ~/Downloads/my-agent.private-key.pem
+```
+
+Use `--from-file` for the key, not `--value`: a PEM is multi-line, and a shell
+that folds or strips those newlines produces a key that fails to parse at mint
+time. `--from-file` stores the bytes verbatim, which is what the RS256 signer
+needs. GitHub's download is a PKCS#1 PEM (`-----BEGIN RSA PRIVATE KEY-----`) and
+is used as-is; no conversion step.
+
+The app id and installation id are identifiers rather than credentials —
+nothing breaks if they leak — but keeping all three in one place means one
+mounting story instead of two.
+
+`flyte create secret` writes to the org unless `--project`/`--domain` scope it.
+Scope the secrets the same way as the environment that reads them, or leave all
+of them org-wide; a secret in the wrong project is invisible at run time.
+
+### Mounting them on the environment
+
+Name the secrets in kebab-case and the env vars come out right on their own:
+`flyte.Secret` upper-cases the key and turns `-` into `_`, so
+`github-app-private-key` mounts as `GITHUB_APP_PRIVATE_KEY`, which is exactly
+what `mint_installation_token()` reads.
+
+```python
+import flyte
+
+env = flyte.TaskEnvironment(
+    name="github-agent",
+    secrets=[
+        flyte.Secret("github-app-id"),
+        flyte.Secret("github-app-installation-id"),
+        flyte.Secret("github-app-private-key"),
+    ],
+    image=flyte.Image.from_debian_base().with_pip_packages("flyteplugins-github[auth]"),
+)
+```
+
+Under any other naming, spell the target out — the env var is the contract, the
+secret name is not:
+
+```python
+flyte.Secret("prod-bot-key", as_env_var="GITHUB_APP_PRIVATE_KEY")
+```
+
+Pass the same `secrets=[...]` to a `WebhookAppEnvironment` when a handler mints
+tokens directly rather than launching a task that does.
+
+### When they are missing
+
+`GITHUB_TOKEN`/`GH_TOKEN` are honored as fallbacks, so a deployment can migrate
+one secret at a time; once the app secrets exist the fallback never fires. A
+deployment with none of them gets `None` back — with a logged reason — rather
+than a crash, so unauthenticated paths keep working. That means a missing
+secret shows up as *unauthenticated behavior*, not an exception: if clones of
+private repos 404, check that all three landed.
+
+## 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.
+GitHub grows actions faster than any constant list; for one the constants do
+not cover yet, qualify the bare type with `action=`:
+
+```python
+@app_env.on_event(events.PullRequest.ANY, action="auto_merge_enabled")
+```
+
+(Raw qualified strings like `"pull_request.auto_merge_enabled"` work too.)
+
+`event.payload` is GitHub's JSON verbatim, typed as `dict[str, Any]`. For
+autocomplete, take a typed view of it — a cast, not a copy or a validation:
+
+```python
+payload = payloads.pull_request(event)  # payload["pull_request"]["head"]["ref"] completes
+payload = payloads.issue_comment(event)  # payload["comment"]["body"], payload["issue"]["number"], ...
+```
+
+## What this plugin does not do
+
+Wrap the GitHub API. Use `PyGithub` directly from your tasks — see
+`examples/external_saas_integrations`. This plugin owns the parts every
+GitHub agent otherwise duplicates: authenticating an inbound delivery and
+turning it into a run, gating a run on a human review, and minting the App
+token the outbound side authenticates with.

flyteplugins_github-2.8.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+flyteplugins/github/__init__.py,sha256=BRBj3eg-RqK6jGcuhv7VUHQFCMKkbEmXn2IMEZqnSDg,4024
+flyteplugins/github/_app_auth.py,sha256=vleBD3urwJYxxIpQJrx6DP1U0eI5f7n8ql-jz9bNZ44,5988
+flyteplugins/github/_provider.py,sha256=ZJFiYc0NeAiWOmVKhnNyAdv4gBDwGdlDVO0TBVJuy30,5305
+flyteplugins/github/_review.py,sha256=6XwWI-lOZ3DIshIRU8i-FrzepJtvXmaVm_wbFAA8Iuw,11037
+flyteplugins/github/events.py,sha256=uEb8QffVdTWdTYQnfkLMcqFw0_kWK-f0rcHzU61DYKo,5224
+flyteplugins/github/payloads.py,sha256=bt27Vw83rWASuXElRLnMdZOhRwGzQjct_2GRqCr3NhM,3734
+flyteplugins_github-2.8.0.dist-info/METADATA,sha256=44dE_oakRj4__YNkoGEtANCxCWO2w14EGa2gFlGjOns,11709
+flyteplugins_github-2.8.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flyteplugins_github-2.8.0.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_github-2.8.0.dist-info/RECORD,,

flyteplugins_github-2.7.2.dist-info/METADATA

@@ -1,127 +0,0 @@
-Metadata-Version: 2.4
-Name: flyteplugins-github
-Version: 2.7.2
-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.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-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.2.dist-info/METADATA,sha256=SXWg8J3AYeRacctnaBEJbIbq5eO5oH8hdJdhn6TGztQ,4231
-flyteplugins_github-2.7.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-flyteplugins_github-2.7.2.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
-flyteplugins_github-2.7.2.dist-info/RECORD,,