imbi-plugin-github 2.11.4__tar.gz → 2.11.6__tar.gz

{imbi_plugin_github-2.11.4 → imbi_plugin_github-2.11.6}/CLAUDE.md

@@ -5,10 +5,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## What This Is
 
 A set of GitHub plugins for the Imbi platform, distributed as a single
-Python package (`imbi_plugin_github`). It ships **three plugin types**
-(identity, deployment, lifecycle), each in **three host flavors**
-(github.com, GitHub Enterprise Cloud, GitHub Enterprise Server) — nine
-plugins total. The Imbi host discovers them through the
+Python package (`imbi_plugin_github`). It ships **one connection plugin**
+plus **one host-agnostic plugin per behavior** — `github-connection`,
+`github-identity`, `github-deployment`, `github-lifecycle`,
+`github-commit-sync`, `github-pr-sync` (six total). There are no longer
+per-flavor (github.com / GHEC / GHES) variants: the operator picks the
+flavor + host once on the connection plugin, and every behavioral plugin
+reads it from there. The Imbi host discovers them through the
 `imbi.plugins` entry points declared in `pyproject.toml`; that table is
 the registration surface — adding a plugin class means adding an entry
 point there.
@@ -38,21 +41,25 @@ over `src`. Python is pinned to **3.14**; ruff uses single quotes and a
 
 ## Architecture
 
-### The base/subclass/host-flavor pattern
+### The connection-plugin / host-agnostic pattern
 
-Every plugin type follows the same shape: one `_*Base` class holds all
-behavior, and three thin concrete subclasses differ *only* in their
-`_resolve_host(options)` classmethod:
+A single `github-connection` plugin (a `ConnectionPlugin` from
+`imbi_common`, with no behavior) carries the `flavor` option
+(`github.com` / `ghec` / `ghes`), the `host` option, and the shared
+App/PAT credentials for the service. Every behavioral plugin is
+host-agnostic and resolves its host from that connection plugin via the
+`github-connection` entry on `ctx.service_plugins`:
 
-- github.com flavor → returns `'github.com'`.
-- GHEC flavor → reads the required `host` option, validates it's a
-  `*.ghe.com` tenant via `require_ghec_tenant_host`.
-- GHES flavor → reads the required `host` option, normalized only.
+- identity / deployment / lifecycle call `_resolve_host(ctx)` →
+  `resolve_connection_host(ctx.service_plugins, label)`.
+- commit-sync / pr-sync resolve it through `_connection_host` /
+  `_resolve_api_base` (the webhook path also falls back to the explicit
+  `api_base_url`, the service endpoint, and the push payload's
+  `repository.url`, in that order).
 
-`_resolve_host` feeds URL construction, and the three backends route
-differently — this mapping is the single most important thing to keep
-consistent and is **duplicated** across the three modules
-(`identity._endpoints`, `deployment._api_base`, `lifecycle._api_base`):
+`resolve_connection_host` returns a bare host; `host_to_api_base` maps it
+to the REST API base. Routing (the single source of truth in
+`host_to_api_base`, with OAuth URLs built in `identity._endpoints`):
 
 | Host                | REST API base                  | OAuth base (identity only)        |
 | ------------------- | ------------------------------ | --------------------------------- |
@@ -60,14 +67,17 @@ consistent and is **duplicated** across the three modules
 | `<tenant>.ghe.com`  | `https://api.<tenant>.ghe.com` | `https://<tenant>.ghe.com/login/oauth` |
 | GHES `<host>`       | `https://<host>/api/v3`        | `https://<host>/login/oauth`      |
 
-When you change routing for one plugin type, check whether the other two
-need the same change.
+The connection plugin must be populated onto `ctx.service_plugins` by the
+host: imbi-gateway already surfaces every service plugin for the webhook
+path; imbi-api populates it for identity/deployment/lifecycle calls.
 
 ### Shared helpers (single sources of truth)
 
-- `_hosts.py` — `normalize_host` (strip/validate a bare hostname, reject
-  paths/ports/queries) and `require_ghec_tenant_host`. All host-option
-  validation lives here.
+- `_hosts.py` — `normalize_host` / `require_ghec_tenant_host` (host-option
+  validation), `flavor_host` (validate a connection plugin's
+  `flavor`+`host` to a bare host), `find_connection` /
+  `resolve_connection_host` (locate the `github-connection` sibling on
+  `service_plugins`), and `host_to_api_base` (bare host → REST API base).
 - `_repos.py` — `resolve_owner_repo(ctx, host, label)` derives the target
   `(owner, repo)` for deployment and lifecycle calls: it scans
   `ctx.project_links` (preferring the `github-repository` key, skipping

{imbi_plugin_github-2.11.4 → imbi_plugin_github-2.11.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbi-plugin-github
-Version: 2.11.4
+Version: 2.11.6
 Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
 Author-email: "Gavin M. Roy" <gavinr@aweber.com>
 License: BSD-3-Clause
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.14
 Requires-Dist: httpx>=0.27
-Requires-Dist: imbi-common[databases]==2.11.4
+Requires-Dist: imbi-common[databases]==2.11.6
 Requires-Dist: pydantic>=2
 Requires-Dist: pyjwt[crypto]>=2.8
 Description-Content-Type: text/markdown

{imbi_plugin_github-2.11.4 → imbi_plugin_github-2.11.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "2.11.4"
+version = "2.11.6"
 description = "GitHub identity plugin for Imbi (github.com / GHEC / GHES)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -16,29 +16,25 @@ classifiers = [
 ]
 dependencies = [
   "httpx>=0.27",
-  "imbi-common[databases]==2.11.4",
+  "imbi-common[databases]==2.11.6",
   "pydantic>=2",
   "pyjwt[crypto]>=2.8",
 ]
 
 [project.entry-points."imbi.plugins"]
-github = "imbi_plugin_github.identity:GitHubPlugin"
-github-enterprise-cloud = "imbi_plugin_github.identity:GitHubEnterpriseCloudPlugin"
-github-enterprise-server = "imbi_plugin_github.identity:GitHubEnterpriseServerPlugin"
+github-connection = "imbi_plugin_github.connection:GitHubConnectionPlugin"
+github-identity = "imbi_plugin_github.identity:GitHubIdentityPlugin"
 github-deployment = "imbi_plugin_github.deployment:GitHubDeploymentPlugin"
-github-deployment-ec = "imbi_plugin_github.deployment:GitHubEnterpriseCloudDeploymentPlugin"
-github-deployment-es = "imbi_plugin_github.deployment:GitHubEnterpriseServerDeploymentPlugin"
 github-lifecycle = "imbi_plugin_github.lifecycle:GitHubLifecyclePlugin"
-github-lifecycle-ec = "imbi_plugin_github.lifecycle:GitHubEnterpriseCloudLifecyclePlugin"
-github-lifecycle-es = "imbi_plugin_github.lifecycle:GitHubEnterpriseServerLifecyclePlugin"
 github-commit-sync = "imbi_plugin_github.commits:GitHubCommitSyncPlugin"
 github-pr-sync = "imbi_plugin_github.pull_requests:GitHubPRSyncPlugin"
+github-doctor = "imbi_plugin_github.doctor:GitHubDoctorPlugin"
 
 [dependency-groups]
 dev = [
   "basedpyright",
   "coverage[toml]",
-  "imbi-common[server,databases]==2.11.4",
+  "imbi-common[server,databases]==2.11.6",
   "pre-commit",
   "pytest",
   "pytest-asyncio",

imbi_plugin_github-2.11.6/src/imbi_plugin_github/__init__.py

@@ -0,0 +1,21 @@
+"""Imbi GitHub plugins.
+
+A single connection plugin holds the flavor/host and shared App/PAT
+credentials for the service; one host-agnostic plugin per behavior
+(identity, deployment, lifecycle, commit-sync, pr-sync, doctor) reads the
+host from that connection plugin.
+"""
+
+from imbi_plugin_github.connection import GitHubConnectionPlugin
+from imbi_plugin_github.deployment import GitHubDeploymentPlugin
+from imbi_plugin_github.doctor import GitHubDoctorPlugin
+from imbi_plugin_github.identity import GitHubIdentityPlugin
+from imbi_plugin_github.lifecycle import GitHubLifecyclePlugin
+
+__all__ = [
+    'GitHubConnectionPlugin',
+    'GitHubDeploymentPlugin',
+    'GitHubDoctorPlugin',
+    'GitHubIdentityPlugin',
+    'GitHubLifecyclePlugin',
+]

imbi_plugin_github-2.11.6/src/imbi_plugin_github/_hosts.py

@@ -0,0 +1,140 @@
+"""Shared host resolution utilities for the GitHub plugins.
+
+Identity (``plugin.py``) and deployment (``deployment.py``) plugins both
+accept a ``host`` option and need to normalise it to a bare hostname
+that URLs can be safely composed against.  This module is the single
+source of truth for that validation.
+"""
+
+from __future__ import annotations
+
+import collections.abc
+import typing
+import urllib.parse
+
+#: Slug of the GitHub connection plugin. A single connection plugin is
+#: attached to each GitHub ``ThirdPartyService`` and carries the
+#: ``flavor`` + ``host`` options (and the shared App/PAT credentials)
+#: that every sibling GitHub plugin reads. Behavioral plugins resolve
+#: their host from this sibling rather than from a per-flavor variant of
+#: their own class.
+GITHUB_CONNECTION_SLUG = 'github-connection'
+
+
+def normalize_host(raw: typing.Any, label: str) -> str:
+    """Validate and normalize a manifest ``host`` value.
+
+    Strips whitespace, accepts an optional scheme, and rejects values
+    with paths / queries / fragments so callers can compose URLs from
+    the result without producing malformed endpoints.
+    """
+    host = str(raw or '').strip()
+    if not host:
+        raise ValueError(f'{label} requires the "host" option')
+    parsed = urllib.parse.urlsplit(
+        host if '://' in host else f'https://{host}'
+    )
+    if (
+        not parsed.hostname
+        or parsed.port is not None
+        or parsed.path not in ('', '/')
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(f'{label} got invalid host value: {host!r}')
+    return parsed.hostname
+
+
+def require_ghec_tenant_host(host: str, label: str) -> str:
+    """Refuse anything that isn't a ``*.ghe.com`` tenant host."""
+    if (
+        not host.endswith('.ghe.com')
+        or host == '.ghe.com'
+        or host.startswith('api.')
+    ):
+        raise ValueError(
+            f'{label} requires a tenant host like "tenant.ghe.com"; '
+            f'got {host!r}'
+        )
+    return host
+
+
+def host_to_api_base(host: str) -> str:
+    """Map a resolved GitHub host to its REST API base.
+
+    The single source of truth for GitHub's flavor routing:
+    ``github.com`` -> ``api.github.com``, a ``*.ghe.com`` tenant ->
+    ``api.<tenant>.ghe.com``, and a GHES appliance -> ``<host>/api/v3``.
+    Shared by every behavioral plugin once it has resolved its host from
+    the connection plugin via :func:`resolve_connection_host`.
+    """
+    if host == 'github.com':
+        return 'https://api.github.com'
+    if host.endswith('.ghe.com'):
+        return f'https://api.{host}'
+    return f'https://{host}/api/v3'
+
+
+class _ConnectionLike(typing.Protocol):
+    """Structural view of an :class:`imbi_common.plugins.ServicePlugin`."""
+
+    slug: str
+    options: dict[str, typing.Any]
+
+
+def flavor_host(options: dict[str, typing.Any], label: str) -> str:
+    """Validate the connection plugin's ``flavor`` + ``host`` to a host.
+
+    The operator picks an explicit ``flavor`` (``github.com`` / ``ghec``
+    / ``ghes``); the ``host`` is required for the two enterprise flavors
+    and ignored for ``github.com``. Returns the bare hostname the rest of
+    the plugin composes URLs against (``github.com``, the validated
+    ``*.ghe.com`` tenant, or the normalized GHES appliance host).
+    """
+    flavor = str(options.get('flavor') or '').strip()
+    if flavor == 'github.com':
+        return 'github.com'
+    if flavor == 'ghec':
+        return require_ghec_tenant_host(
+            normalize_host(options.get('host'), label), label
+        )
+    if flavor == 'ghes':
+        return normalize_host(options.get('host'), label)
+    raise ValueError(
+        f'{label} got invalid connection flavor {flavor!r}; expected one '
+        f'of "github.com", "ghec", or "ghes"'
+    )
+
+
+def find_connection(
+    service_plugins: collections.abc.Iterable[_ConnectionLike],
+) -> _ConnectionLike | None:
+    """Return the ``github-connection`` sibling, or ``None`` if absent.
+
+    Locates the connection plugin without validating its options, so
+    callers that want to fall back when no connection plugin is attached
+    (the webhook path) can distinguish "absent" from "misconfigured".
+    """
+    for plugin in service_plugins:
+        if plugin.slug == GITHUB_CONNECTION_SLUG:
+            return plugin
+    return None
+
+
+def resolve_connection_host(
+    service_plugins: collections.abc.Iterable[_ConnectionLike], label: str
+) -> str:
+    """Return the GitHub host from the connection plugin sibling.
+
+    Scans ``service_plugins`` for the single ``github-connection`` entry
+    and resolves its ``flavor`` + ``host`` to a bare hostname. Raises
+    ``ValueError`` (operator-facing) when no connection plugin is
+    attached to the service or its flavor/host is unusable.
+    """
+    plugin = find_connection(service_plugins)
+    if plugin is None:
+        raise ValueError(
+            f'{label}: no {GITHUB_CONNECTION_SLUG} plugin is attached to '
+            f'the service; cannot resolve the GitHub host'
+        )
+    return flavor_host(plugin.options, label)

{imbi_plugin_github-2.11.4 → imbi_plugin_github-2.11.6}/src/imbi_plugin_github/commits.py

@@ -54,16 +54,15 @@ from imbi_common.plugins.base import (
     CredentialField,
     PluginContext,
     PluginManifest,
-    ServicePlugin,
     WebhookActionPlugin,
 )
 from imbi_common.plugins.errors import PluginRateLimited
 
 from imbi_plugin_github import _app_auth
 from imbi_plugin_github._hosts import (
+    find_connection,
+    flavor_host,
     host_to_api_base,
-    normalize_host,
-    require_ghec_tenant_host,
 )
 from imbi_plugin_github._repos import resolve_owner_repo
 from imbi_plugin_github.deployment import (
@@ -82,10 +81,6 @@ LOGGER = logging.getLogger(__name__)
 
 _HTTP_TIMEOUT_SECONDS = 10.0
 _ZERO_SHA = '0' * 40
-# This plugin's own slug; skipped when reading the GitHub host/flavor
-# from connected ``service_plugins`` so the commit-sync entry can't
-# masquerade as a github.com host on a GHEC/GHES service.
-_SELF_SLUG = 'github-commit-sync'
 # GitHub's compare endpoint caps ``commits[]`` at 250 per page and
 # paginates the rest; bound the walk so a pathological single push
 # (force-push of thousands of commits) can't pin us on one endpoint.
@@ -309,32 +304,26 @@ def _branch_short_name(ref: str) -> str:
     return ref.removeprefix(prefix)
 
 
-def _github_plugin_host(plugin: ServicePlugin) -> str | None:
-    """Resolve the GitHub host from a connected plugin's slug + options.
+def _connection_host(ctx: PluginContext, label: str) -> str | None:
+    """Resolve the GitHub host from the ``github-connection`` sibling.
 
-    Returns ``None`` for non-GitHub plugins and for GitHub plugins whose
-    required ``host`` option is missing or invalid (logged) so the caller
-    can fall through to the next resolution source.
+    Returns ``None`` when no connection plugin is attached so callers can
+    fall through to the next resolution source. A connection plugin that
+    *is* present but carries an unusable flavor/host is logged and also
+    treated as a fall-through rather than failing the delivery.
     """
-    slug = plugin.slug
-    if not slug.startswith('github'):
+    plugin = find_connection(ctx.service_plugins)
+    if plugin is None:
         return None
-    label = f'github-commit-sync (via {slug})'
     try:
-        if slug.endswith('-ec') or slug == 'github-enterprise-cloud':
-            return require_ghec_tenant_host(
-                normalize_host(plugin.options.get('host'), label), label
-            )
-        if slug.endswith('-es') or slug == 'github-enterprise-server':
-            return normalize_host(plugin.options.get('host'), label)
+        return flavor_host(plugin.options, label)
     except ValueError as exc:
         LOGGER.warning(
-            'Connected GitHub plugin %r has an unusable host option: %s',
-            slug,
+            '%s: github-connection plugin has an unusable flavor/host: %s',
+            label,
             exc,
         )
         return None
-    return 'github.com'
 
 
 def _api_base_from_repo_url(repo_url: object) -> str | None:
@@ -363,15 +352,9 @@ def _resolve_api_base(
     """Pick the GitHub API base for this call (see module docstring)."""
     if explicit:
         return explicit.rstrip('/')
-    for plugin in ctx.service_plugins:
-        # Skip our own entry: its slug starts with "github" but carries
-        # no host option, so _github_plugin_host would mis-resolve it to
-        # github.com on a GHEC/GHES service.
-        if plugin.slug == _SELF_SLUG:
-            continue
-        host = _github_plugin_host(plugin)
-        if host:
-            return host_to_api_base(host)
+    host = _connection_host(ctx, 'github-commit-sync')
+    if host:
+        return host_to_api_base(host)
     endpoint = ctx.assignment_options.get('service_endpoint')
     if isinstance(endpoint, str) and endpoint:
         return endpoint.rstrip('/')
@@ -732,20 +715,12 @@ async def _hydrate_ci(
 def _resolve_host_for_context(ctx: PluginContext) -> str | None:
     """Resolve the GitHub web host for an on-demand sync (no payload).
 
-    Walks the connected GitHub plugins on ``ctx.service_plugins`` and
-    returns the first usable host (github.com, a GHEC tenant, or a GHES
-    appliance), skipping this plugin's own entry so a commit-sync row on a
-    GHEC/GHES service can't be read as github.com.  Unlike the webhook
-    path there is no push payload to fall back to, so the absence of a
-    connected GitHub plugin yields ``None``.
+    Reads the ``github-connection`` sibling on ``ctx.service_plugins``
+    and returns its resolved host (github.com, a GHEC tenant, or a GHES
+    appliance). Unlike the webhook path there is no push payload to fall
+    back to, so the absence of a connection plugin yields ``None``.
     """
-    for plugin in ctx.service_plugins:
-        if plugin.slug == _SELF_SLUG:
-            continue
-        host = _github_plugin_host(plugin)
-        if host:
-            return host
-    return None
+    return _connection_host(ctx, 'github-commit-sync')
 
 
 async def _fetch_default_branch(

imbi_plugin_github-2.11.6/src/imbi_plugin_github/connection.py

@@ -0,0 +1,79 @@
+"""GitHub connection plugin.
+
+A single connection plugin is attached to each GitHub
+``ThirdPartyService`` and is the one place an operator configures the
+GitHub flavor / host and the shared server-to-server credentials. It
+carries no behavior of its own -- the identity, deployment, lifecycle,
+and commit-/pr-sync plugins read its ``flavor`` + ``host`` options off
+``ctx.service_plugins`` to resolve their host, and the Imbi host
+resolves their App/PAT credentials from this plugin's
+``plugin_configuration`` when they carry none themselves.
+
+The identity plugin keeps its own OAuth App ``client_id`` /
+``client_secret`` (a GitHub OAuth App is a separate registration from a
+GitHub App), so those credentials are deliberately *not* declared here.
+"""
+
+from __future__ import annotations
+
+from imbi_common.plugins.base import (
+    ConnectionPlugin,
+    CredentialField,
+    PluginManifest,
+    PluginOption,
+)
+
+
+class GitHubConnectionPlugin(ConnectionPlugin):
+    manifest = PluginManifest(
+        slug='github-connection',
+        name='GitHub Connection',
+        description=(
+            'Holds the GitHub flavor/host and shared App/PAT credentials '
+            'for every GitHub plugin on the service.'
+        ),
+        plugin_type='connection',
+        auth_type='api_token',
+        options=[
+            PluginOption(
+                name='flavor',
+                label='Flavor',
+                description=(
+                    'github.com, GitHub Enterprise Cloud (ghec), or '
+                    'GitHub Enterprise Server (ghes).'
+                ),
+                type='string',
+                choices=['github.com', 'ghec', 'ghes'],
+                required=True,
+            ),
+            PluginOption(
+                name='host',
+                label='Host',
+                description=(
+                    'Tenant host (tenant.ghe.com) for ghec or the '
+                    'appliance hostname for ghes; ignored for github.com.'
+                ),
+                type='string',
+            ),
+        ],
+        credentials=[
+            CredentialField(
+                name='app_id',
+                label='GitHub App ID',
+                description='GitHub App ID (App auth).',
+                required=False,
+            ),
+            CredentialField(
+                name='private_key',
+                label='GitHub App private key',
+                description='PEM or base64-encoded PEM (App auth).',
+                required=False,
+            ),
+            CredentialField(
+                name='access_token',
+                label='Personal access token',
+                description='PAT used when not using App auth.',
+                required=False,
+            ),
+        ],
+    )