imbi-plugin-github 1.0.0__tar.gz → 1.1.0__tar.gz

imbi_plugin_github-1.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: imbi-plugin-github
+Version: 1.1.0
+Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: imbi-common>=0.11.0
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# imbi-plugin-github
+
+GitHub plugins for Imbi. Three flavors (github.com, GitHub Enterprise Cloud,
+GitHub Enterprise Server) of each plugin type so the admin UI can wire
+projects to the right backend.
+
+## Plugin types
+
+| Type       | Slugs                                                                |
+| ---------- | -------------------------------------------------------------------- |
+| Identity   | `github`, `github-enterprise-cloud`, `github-enterprise-server`      |
+| Deployment | `github-deployment`, `github-deployment-ec`, `github-deployment-es`  |
+| Lifecycle  | `github-lifecycle`, `github-lifecycle-ec`, `github-lifecycle-es`     |
+
+### Identity
+
+Phase 1 ships the OAuth App flow only; GitHub App installation tokens are
+deferred. The access token returned by the OAuth grant is passed straight
+to GitHub APIs as a `Bearer` token, so `materialize()` is a no-op.
+
+### Deployment
+
+Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
+plus tag and release creation. See `deployment.py` for the per-environment
+`DEPLOYS_VIA` edge contract.
+
+### Lifecycle
+
+Reacts to project archive / unarchive by archiving the matching repo via
+`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
+`archive_target_org` option is set, archive **also** transfers the repo to
+that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
+moving sunset projects into a dedicated "archive" org so they no longer
+crowd primary-org searches.
+
+GitHub refuses to transfer archived repos, so an already-archived source
+is briefly unarchived, transferred, and re-archived at the destination.
+On unarchive the plugin only flips `archived` back to `false` at the
+repo's current location — it does **not** transfer back to the original
+org.
+
+Archiving requires admin scope on the repo; transferring additionally
+requires admin permission on the target organization.
+
+## Manifest options (identity)
+
+| Option           | Required  | Description                                                                |
+| ---------------- | --------- | -------------------------------------------------------------------------- |
+| `host`           | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`).    |
+| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email`).    |
+
+## Credentials (identity)
+
+| Field            | Required |
+| ---------------- | -------- |
+| `client_id`      | yes      |
+| `client_secret`  | yes      |
+
+## License
+
+BSD-3-Clause.

imbi_plugin_github-1.1.0/README.md

@@ -0,0 +1,61 @@
+# imbi-plugin-github
+
+GitHub plugins for Imbi. Three flavors (github.com, GitHub Enterprise Cloud,
+GitHub Enterprise Server) of each plugin type so the admin UI can wire
+projects to the right backend.
+
+## Plugin types
+
+| Type       | Slugs                                                                |
+| ---------- | -------------------------------------------------------------------- |
+| Identity   | `github`, `github-enterprise-cloud`, `github-enterprise-server`      |
+| Deployment | `github-deployment`, `github-deployment-ec`, `github-deployment-es`  |
+| Lifecycle  | `github-lifecycle`, `github-lifecycle-ec`, `github-lifecycle-es`     |
+
+### Identity
+
+Phase 1 ships the OAuth App flow only; GitHub App installation tokens are
+deferred. The access token returned by the OAuth grant is passed straight
+to GitHub APIs as a `Bearer` token, so `materialize()` is a no-op.
+
+### Deployment
+
+Drives the GitHub Deployments API (`POST /repos/{owner}/{repo}/deployments`)
+plus tag and release creation. See `deployment.py` for the per-environment
+`DEPLOYS_VIA` edge contract.
+
+### Lifecycle
+
+Reacts to project archive / unarchive by archiving the matching repo via
+`PATCH /repos/{owner}/{repo}` with `{"archived": true|false}`. When the
+`archive_target_org` option is set, archive **also** transfers the repo to
+that org first via `POST /repos/{owner}/{repo}/transfer` — useful for
+moving sunset projects into a dedicated "archive" org so they no longer
+crowd primary-org searches.
+
+GitHub refuses to transfer archived repos, so an already-archived source
+is briefly unarchived, transferred, and re-archived at the destination.
+On unarchive the plugin only flips `archived` back to `false` at the
+repo's current location — it does **not** transfer back to the original
+org.
+
+Archiving requires admin scope on the repo; transferring additionally
+requires admin permission on the target organization.
+
+## Manifest options (identity)
+
+| Option           | Required  | Description                                                                |
+| ---------------- | --------- | -------------------------------------------------------------------------- |
+| `host`           | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`).    |
+| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email`).    |
+
+## Credentials (identity)
+
+| Field            | Required |
+| ---------------- | -------- |
+| `client_id`      | yes      |
+| `client_secret`  | yes      |
+
+## License
+
+BSD-3-Clause.

{imbi_plugin_github-1.0.0 → imbi_plugin_github-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-plugin-github"
-version = "1.0.0"
+version = "1.1.0"
 description = "GitHub identity plugin for Imbi (github.com / GHEC / GHES)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -16,7 +16,7 @@ classifiers = [
 ]
 dependencies = [
   "httpx>=0.27",
-  "imbi-common>=0.8.4",
+  "imbi-common>=0.11.0",
   "pydantic>=2",
 ]
 
@@ -27,6 +27,9 @@ github-enterprise-server = "imbi_plugin_github.identity:GitHubEnterpriseServerPl
 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"
 
 [dependency-groups]
 dev = [

imbi_plugin_github-1.1.0/src/imbi_plugin_github/_repos.py

@@ -0,0 +1,113 @@
+"""Shared owner/repo resolution for the GitHub plugin family.
+
+Identity, deployment, and lifecycle plugins all derive ``(owner, repo)``
+from a project's external links (preferring the ``github-repository``
+link key) plus, as a final fallback, the project's slug and type slug.
+Centralising the logic here keeps the rules — reserved GitHub URL
+prefixes, ``.git`` stripping, host case-folding — in one place so every
+plugin agrees on what counts as a "real" repo URL.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+
+from imbi_common.plugins.base import PluginContext
+
+# Reserved GitHub URL prefixes that share the host with repository URLs
+# but never point at a real ``<owner>/<repo>`` pair.  Any link whose
+# first path segment matches one of these is skipped during owner/repo
+# derivation so e.g. ``github.com/orgs/<org>`` or a marketplace link
+# can't silently bind a plugin to the wrong target.
+_RESERVED_LINK_PREFIXES = frozenset(
+    {
+        'orgs',
+        'marketplace',
+        'settings',
+        'enterprises',
+        'features',
+        'pricing',
+        'about',
+        'login',
+        'logout',
+        'signup',
+        'sponsors',
+        'topics',
+        'collections',
+        'trending',
+        'codespaces',
+        'notifications',
+        'issues',
+        'pulls',
+        'search',
+        'stars',
+        'explore',
+    }
+)
+
+
+def parse_owner_repo(url: str, target_host: str) -> tuple[str, str] | None:
+    """Extract ``(owner, repo)`` from ``url`` when it is a repo URL on
+    ``target_host``.  Returns ``None`` for other hosts, short paths,
+    or reserved-prefix paths like ``/orgs/<org>``.
+    """
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except ValueError:
+        return None
+    if (parsed.hostname or '').lower() != target_host:
+        return None
+    parts = [p for p in parsed.path.split('/') if p]
+    if len(parts) < 2:
+        return None
+    if parts[0].lower() in _RESERVED_LINK_PREFIXES:
+        return None
+    return parts[0], parts[1].removesuffix('.git')
+
+
+def derive_owner_repo_from_links(
+    links: dict[str, str], host: str
+) -> tuple[str, str] | None:
+    """Find a project link pointing at ``host`` and parse owner/repo.
+
+    Prefers an explicit ``github-repository`` link key when one is
+    present and points at ``host``; otherwise scans the remaining
+    same-host links and returns the first usable one.  Returns
+    ``None`` when nothing matches.
+    """
+    target = host.lower()
+    preferred = links.get('github-repository')
+    if preferred is not None:
+        owner_repo = parse_owner_repo(preferred, target)
+        if owner_repo is not None:
+            return owner_repo
+    for key, url in links.items():
+        if key == 'github-repository':
+            continue
+        owner_repo = parse_owner_repo(url, target)
+        if owner_repo is not None:
+            return owner_repo
+    return None
+
+
+def resolve_owner_repo(
+    ctx: PluginContext, host: str, plugin_label: str
+) -> tuple[str, str]:
+    """Resolve the repo for a plugin call from ``ctx``.
+
+    First tries the project links; falls back to
+    ``<project_type_slug>/<project_slug>`` as a convention.  Raises
+    :class:`ValueError` when neither path produces a candidate so the
+    caller can surface a clear "set the GitHub Repository link"
+    message to the operator.
+    """
+    derived = derive_owner_repo_from_links(ctx.project_links, host)
+    if derived is not None:
+        return derived
+    if ctx.project_type_slugs and ctx.project_slug:
+        return ctx.project_type_slugs[0], ctx.project_slug
+    raise ValueError(
+        f'{plugin_label} could not determine the target repository: '
+        "set the project's GitHub Repository link or tag the project "
+        'with a ProjectType'
+    )